Bu sayfa, Cloud Translation API ile çevrilmiştir.

Places UI Kit ile Etkileşimli Mağaza Bulma Aracı oluşturma

Hedef

Bu dokümanda, Google Haritalar Platformu'nu (özellikle Maps JavaScript API ve Yerler Kullanıcı Arayüzü Kiti: Yer Ayrıntıları Öğesi) kullanarak etkileşimli bir mağaza bulucu uygulaması geliştirmenin temel adımları açıklanmaktadır. Mağaza konumlarını gösteren bir harita oluşturmayı, görünen mağazaların listesini dinamik olarak güncellemeyi ve her mağaza için zengin yer bilgilerini göstermeyi öğreneceksiniz.

Ön koşullar

Aşağıdaki konularda bilgi sahibi olmanız önerilir:

Maps JavaScript API: Sayfanızda harita göstermek ve Yerler kullanıcı arayüzü kitini içe aktarmak için kullanılır.
Gelişmiş İşaretçiler: Haritada işaretçileri görüntülemek için kullanılır.
Places UI Kit: Mağazalarınızla ilgili bilgileri kullanıcı arayüzünde görüntülemek için kullanılır.

Projenizde Maps JavaScript API ve Yerler Kullanıcı Arayüzü Kiti'ni etkinleştirin.

Başlamadan önce Haritalar JavaScript API'yi yüklediğinizden ve Gelişmiş İşaretçiler ile Yerler Kullanıcı Arayüzü Kiti için gerekli kitaplıkları içe aktardığınızdan emin olun. Bu dokümanda, HTML, CSS ve JavaScript dahil olmak üzere web geliştirme hakkında bilgi sahibi olduğunuz varsayılır.

İlk kurulum

İlk adım, sayfaya bir harita eklemektir. Bu harita, mağaza konumlarınızla ilgili raptiyeleri göstermek için kullanılır.

Bir sayfaya harita eklemenin iki yolu vardır:

gmp-map HTML web bileşenini kullanma
JavaScript'i kullanma

Kullanım alanınız için en uygun yöntemi seçin. Haritayı uygulamanın her iki yolu da bu kılavuzda kullanılabilir.

Demo

Bu demoda, San Francisco Körfez Bölgesi'ndeki Google ofis konumlarını gösteren mağaza bulucu örneği gösterilmektedir. Yer Ayrıntıları Öğesi, her konum için bazı örnek özelliklerle birlikte gösterilir.

Mağaza konumlarını yükleme ve görüntüleme

Bu bölümde, mağaza verilerinizi haritaya yükleyip göstereceğiz. Bu kılavuzda, mevcut mağazalarınızla ilgili bilgilerin bulunduğu bir bilgi deposuna sahip olduğunuz varsayılmaktadır. Mağaza verileriniz veritabanınız gibi çeşitli kaynaklardan gelebilir. Bu örnekte, her biri bir mağaza konumunu temsil eden bir mağaza nesnesi dizisi içeren yerel bir JSON dosyası (stores.json) varsayılır. Her nesne en az bir name, location (lat ve lng ile) ve place_id içermelidir.

Henüz yoksa mağaza konumlarınızın yer kimliklerini çeşitli yöntemlerle alabilirsiniz. Daha fazla bilgi için yer kimliği dokümanlarına bakın.

stores.json dosyanızdaki örnek bir mağaza ayrıntıları girişi aşağıdaki gibi görünebilir. Ad, Konum (lat/lng) ve Yer Kimliği alanları vardır. Mağazanın çalışma saatlerini (kısaltılmış) içeren bir nesne vardır. Ayrıca, mağaza konumunun özel özelliklerini tanımlamaya yardımcı olacak iki boole değeri de vardır.

{
  "name": "Example Store Alpha",
  "location": { "lat": 51.51, "lng": -0.12 },
  "place_id": "YOUR_STORE_PLACE_ID",
  "opening_hours": { "Monday": "09:00 - 17:00", "...": "..." },
  "new_store_design": true,
  "indoor_seating": false
}

JavaScript kodunuzda mağaza konumlarınızın verilerini getirin ve her biri için haritada bir raptiye gösterin.

Bunu nasıl yapacağınıza dair bir örnek aşağıda verilmiştir. Bu işlev, mağazaların ayrıntılarını içeren bir nesne alır ve her birinin konumuna göre bir işaretçi oluşturur.

function displayInitialMarkers(storeLocations) {
    if (!AdvancedMarkerElement || !LatLng || !mapElement) return;
    storeLocations.forEach(store => {
        if (store.location) {
            const marker = new AdvancedMarkerElement({
                position: new LatLng(store.location.lat, store.location.lng),
                title: store.name
            });
            mapElement.appendChild(marker);
        }
    });
}

Mağazalarınızı yükledikten ve konumlarını temsil eden raptiyeleri haritada görüntüledikten sonra, mağazalarınızla ilgili ayrıntıları görüntülemek için HTML ve CSS kullanarak bir kenar çubuğu oluşturun.

Mağaza bulucu özelliğinizin bu aşamada nasıl görünebileceğine dair bir örnek aşağıda verilmiştir:

resim

Harita görüntü alanı değişikliklerini dinleme

Performansı ve kullanıcı deneyimini optimize etmek için uygulamanızı, kenar çubuğundaki işaretçileri ve ayrıntıları yalnızca ilgili konumlar görünür harita alanında (görünüm alanı) olduğunda gösterecek şekilde güncelleyin. Bu işlem, harita görüntü alanı değişikliklerini dinlemeyi, bu etkinlikleri hata ayıklamayı ve ardından yalnızca gerekli işaretçileri yeniden çizmeyi içerir.

Haritanın boş etkinlik özelliğine bir etkinlik işleyici ekleyin. Bu etkinlik, kaydırma veya yakınlaştırma işlemleri tamamlandıktan sonra tetiklenir ve hesaplamalarınız için kararlı bir görüntü alanı sağlar.

map.addListener('idle', debounce(updateMarkersInView, 300));

Yukarıdaki kod snippet'i, idle etkinliğini dinler ve bir debounce işlevi çağırır. Bir debounce işlevi kullanmak, işaretçi güncelleme mantığınızın yalnızca kullanıcı harita ile etkileşimi kısa bir süre durdurduktan sonra çalışmasını sağlar ve performansı artırır.

function debounce(func, delay) {
    let timeoutId;
    return function(...args) {
        const context = this;
        clearTimeout(timeoutId);
        timeoutId = setTimeout(() => {
            func.apply(context, args);
        }, delay);
    };
}

Yukarıdaki kod, örnek bir gecikmeli işlevdir. Bir işlev ve gecikme bağımsız değişkeni alır. Bu bağımsız değişken, boşta dinleyiciye aktarıldığı şekilde görülebilir. 300 ms gecikme, haritanın hareket etmeyi durdurmasını beklemek için yeterlidir ve kullanıcı arayüzüne belirgin bir gecikme eklemez. Bu zaman aşımı sona erdiğinde, iletilen işlev çağrılır. Bu durumda updateMarkersInView işlevi çağrılır.

updateMarkersInView işlevi aşağıdaki işlemleri yapmalıdır:

Haritadaki tüm mevcut işaretçileri temizleme

Mağazanın konumunun mevcut harita sınırları içinde olup olmadığını kontrol edin. Örneğin:

if (map.getBounds().contains(storeLatLng)) {
  // logic
}

Yukarıdaki if ifadesinde, mağaza konumu harita görüntü alanının içine düşerse işaretleri ve mağaza ayrıntılarını yan çubukta görüntüleyecek kod yazın.

Yer Ayrıntıları öğesini kullanarak zengin yer ayrıntılarını görüntüleme

Bu aşamada uygulama tüm mağaza konumlarını gösterir ve kullanıcılar bunları harita görüntü alanına göre filtreleyebilir. Bu deneyimi iyileştirmek için Yer Ayrıntıları Öğesi kullanılarak her mağazayla ilgili fotoğraflar, yorumlar ve erişilebilirlik bilgileri gibi zengin ayrıntılar eklenir. Bu örnekte özellikle Yer Ayrıntıları Kompakt Öğesi kullanılmaktadır.

Veri kaynağınızdaki her mağaza konumunun karşılık gelen bir yer kimliği olmalıdır. Bu kimlik, konumu Google Haritalar'da benzersiz şekilde tanımlar ve konumun ayrıntılarını almak için gereklidir. Bu yer kimliklerini genellikle önceden edinir ve mağaza kayıtlarınızın her biri için depolarsınız.

Yer Ayrıntıları Kompakt Öğesini uygulamaya entegre etme

Bir mağazanın mevcut harita görüntü alanında olduğu ve kenar çubuğunda oluşturulduğu belirlendiğinde, mağaza için dinamik olarak bir Yer Ayrıntıları Kompakt Öğesi oluşturup ekleyebilirsiniz.

İşlenen mevcut mağaza için verilerinizden yer kimliğini alın. Yer kimliği, öğenin hangi yerde gösterileceğini kontrol etmek için kullanılır.

JavaScript'te PlaceDetailsCompactElement örneğini dinamik olarak oluşturun. Ayrıca yeni bir PlaceDetailsPlaceRequestElement oluşturulur, yer kimliği ona iletilir ve bu PlaceDetailsCompactElement'a eklenir. Son olarak, öğenin göstereceği içeriği yapılandırmak için PlaceContentConfigElement öğesini kullanın.

Aşağıdaki işlevde, gerekli Place UI Kit kitaplıklarının içe aktarıldığı ve bu işlevin çağrıldığı kapsamda kullanılabildiği ve işleve iletilen storeData değerinin place_id içerdiği varsayılır.

Bu işlev öğeyi döndürür ve çağıran kod, öğeyi DOM'a eklemekten sorumludur.

function createPlaceDetailsCompactElement(storeData) {
    // Create the main details component
    const detailsCompact = new PlaceDetailsCompactElement();
    detailsCompact.setAttribute('orientation', 'vertical'); // Or 'horizontal'

    // Specify the Place ID
    const placeRequest = new PlaceDetailsPlaceRequestElement();
    placeRequest.place = storeData.place_id;
    detailsCompact.appendChild(placeRequest);

    // Configure which content elements to display
    const contentConfig = new PlaceContentConfigElement();
    // For this example, we'll render media, rating, accessibility, and attribution:
    contentConfig.appendChild(new PlaceMediaElement({ lightboxPreferred: true }));
    contentConfig.appendChild(new PlaceRatingElement());
    contentConfig.appendChild(new PlaceAccessibleEntranceIconElement());
    // Configure attribution
    const placeAttribution = new PlaceAttributionElement();
    placeAttribution.setAttribute('light-scheme-color', 'gray');
    placeAttribution.setAttribute('dark-scheme-color', 'gray');
    contentConfig.appendChild(placeAttribution);
    detailsCompact.appendChild(contentConfig);
    // Return the element
    return detailsCompact;
}

Yukarıdaki örnek kodda öğe, yer fotoğraflarını, yorum puanını ve erişilebilirlik bilgilerini gösterecek şekilde yapılandırılmıştır. Bu, mevcut diğer içerik öğelerini ekleyerek veya kaldırarak özelleştirilebilir. Mevcut tüm seçenekler için PlaceContentConfigElement dokümanlarına bakın.

Yer Ayrıntıları Kompakt Öğesi, CSS özel özellikleri aracılığıyla stil oluşturmayı destekler. Bu sayede, görünümünü (renkler, yazı tipleri vb.) uygulamanızın tasarımına uyacak şekilde özelleştirebilirsiniz. Bu özel özellikleri CSS dosyanıza uygulayın. Desteklenen CSS özellikleri için PlaceDetailsCompactElement referans dokümanlarına bakın.

Başvurunuzun bu aşamada nasıl görünebileceğine dair örnek:

resim

Mağaza bulucu özelliğini geliştirme

Mağaza bulucu uygulamanız için sağlam bir temel oluşturdunuz. Artık işlevini genişletmenin ve daha da zengin, kullanıcı odaklı bir deneyim oluşturmanın çeşitli yollarını düşünebilirsiniz.

Otomatik Tamamlama Ekleyin

Bir arama girişini Yer Otomatik Tamamlama ile entegre ederek kullanıcıların mağaza aradıkları alanları bulma şeklini iyileştirin. Kullanıcılar bir adres, mahalle veya önemli yer yazıp bir öneri seçtiğinde haritayı otomatik olarak bu konumu merkezleyecek şekilde programlayın. Böylece yakındaki mağazaların güncellenmesi tetiklenir. Bunu yapmak için bir giriş alanı ekleyin ve bu alana Yer Otomatik Tamamlama işlevini ekleyin. Bir öneri seçildiğinde harita bu noktada merkezlenebilir. Sonuçları operasyon bölgenize göre yönlendirecek veya kısıtlayacak şekilde yapılandırmayı unutmayın.

Konumu algılama

Mevcut coğrafi konumlarını algılama işlevini uygulayarak özellikle mobil kullanıcılar için anında alaka düzeyi sunun. Kullanıcının konumunu algılamak için tarayıcı izni aldıktan sonra haritayı kullanıcının konumuna göre otomatik olarak merkezleyin ve en yakın mağazaları gösterin. Kullanıcılar anında seçenekler ararken bu Yakınımdaki özelliğine büyük önem verir. Konum erişimi isteğinde bulunmak için bir düğme veya ilk istem ekleyin.

Mesafeyi ve yol tarifini göster

Kullanıcılar ilgilendikleri bir mağazayı belirledikten sonra Routes API'yi entegre ederek yolculuklarını önemli ölçüde iyileştirin. Listelediğiniz her mağaza için kullanıcının mevcut konumuna veya aranan konuma olan uzaklığı hesaplayın ve gösterin. Ayrıca, kullanıcının konumundan seçili mağazaya rota oluşturmak için Routes API'yi kullanan bir düğme veya bağlantı sağlayın. Ardından bu rotayı haritanızda görüntüleyebilir veya navigasyon için Google Haritalar'a bağlantı vererek bir mağazayı bulma ile oraya gitme arasında sorunsuz bir geçiş sağlayabilirsiniz.

Bu uzantıları uygulayarak, doğrudan yaygın kullanıcı ihtiyaçlarını karşılayan daha kapsamlı ve kullanışlı bir mağaza bulucu oluşturmak için Google Haritalar Platformu'nun daha fazla özelliğini kullanabilirsiniz.

Sonuç

Bu kılavuzda, etkileşimli bir mağaza bulucu oluşturmayla ilgili temel adımlar gösterilmiştir. Maps JavaScript API'yi kullanarak kendi mağaza konumlarınızı bir haritada nasıl göstereceğinizi, görüntülenen mağazaları görüntü alanı değişikliklerine göre dinamik olarak nasıl güncelleyeceğinizi ve en önemlisi, kendi mağaza verilerinizi Places kullanıcı arayüzü kitine uygun şekilde nasıl göstereceğinizi öğrendiniz. Yer kimlikleri dahil olmak üzere mevcut mağaza bilgilerinizi Yer Ayrıntıları Öğesi ile kullanarak konumlarınızın her biri için zengin ve standartlaştırılmış ayrıntılar sunabilir, böylece kullanıcı dostu bir mağaza bulucu için sağlam bir temel oluşturabilirsiniz.

Gelişmiş konum tabanlı uygulamaları hızlı bir şekilde geliştirmek için güçlü, bileşen tabanlı araçlar sunmak üzere Maps JavaScript API ve Places UI Kit'i deneyin. Bu özellikleri birleştirerek kullanıcılarınız için ilgi çekici ve bilgilendirici deneyimler oluşturabilirsiniz.

Katkıda bulunanlar

Henrik Valve | DevX Mühendisi

Places UI Kit ile Etkileşimli Mağaza Bulma Aracı oluşturma Koleksiyonlar ile düzeninizi koruyun İçeriği tercihlerinize göre kaydedin ve kategorilere ayırın.