Hedef
Kullanıcıların yakında arama veya metin arama özelliğini kullanarak yerleri bulmasına yardımcı olmak ve önemli yerleri keşfetme becerilerini geliştirmek için PlaceSearchElement ile Google Haritalar'ı nasıl entegre edeceğinizi öğrenin. Uygulamanızda gösterilen yerler hakkında daha fazla ayrıntı sağlamak için Place Details Compact Element'i kullanın.
PlaceSearchElement nedir?
PlaceSearchElement, Maps JavaScript API'deki Places UI Kit'in bir parçasıdır. Bu, yer arama sonuçlarını doğrudan uygulamanızda liste biçiminde gösteren bir HTML öğesidir. Bu öğe, Yakında Arama veya Metin Arama kullanılarak bulunan yerleri gösterme sürecini basitleştirerek yer keşfi için sorunsuz bir kullanıcı deneyimi sunar. Kullanıcı listeden bir yer seçtiğinde, genellikle bir bilgi penceresi ve Yer Ayrıntıları öğesini kullanarak yerin ayrıntılarını haritada gösterebilirsiniz.
Yer keşfini görselleştirme
Aşağıdaki resimde PlaceSearchElement özelliğinin kullanımına dair bir örnek gösterilmektedir. Sol tarafta restoranların listesi (PlaceSearchElement) gösterilir. Bir restoran seçildiğinde, restoranın ayrıntıları haritadaki bir bilgi penceresinde gösterilir ve harita, restoranın konumunu ortalar.
Yer Keşfi'nin kullanım alanları
PlaceSearchElement'ı entegre etmek, farklı sektörlerdeki çeşitli uygulamaları geliştirebilir:
- Seyahat ve Turizm: Turistlerin bir bölgedeki turistik yerleri, otelleri veya belirli mutfak türlerini aramasına olanak tanıyın.
- Emlak: Potansiyel alıcıların veya kiracıların yakındaki okulları, süpermarketleri ya da toplu taşıma seçeneklerini bulmasını sağlayın.
- Lojistik ve hizmetler: Sürücülerin elektrikli araç şarj istasyonlarını, benzin istasyonlarını veya belirli servis merkezlerini bulmasına yardımcı olun.
Çözüm İş Akışı: Place Discovery'yi Uygulama
Bu bölümde, haritadaki yerleri keşfetmek için PlaceSearchElement'i nasıl entegre edeceğiniz açıklanmakta ve Places UI Kit ile etkileşim kurmak için kod snippet'leri yer almaktadır. Haritayı nasıl başlatacağınızı ve hem Yakında Arama hem de Metin Arama'yı nasıl uygulayacağınızı öğrenin. Son olarak, kullanıcı haritada bir yerin raptiyesini tıkladığında o yerle ilgili daha fazla ayrıntı göstermek için Yer Ayrıntıları öğesini kullanın.
Ön koşullar
Aşağıdaki dokümanları incelemeniz önerilir:
PlaceSearchElement- Yakında Arama veya Metin Arama'yı kullanarak yerleri göstermek için kullanılır.- Yer Ayrıntıları Öğesi - Belirli bir yerin ayrıntılarını görüntülemek için kullanılır.
- Maps JavaScript API: Sayfanızda harita göstermek ve Places UI Kit'i içe aktarmak için kullanılır.
Projenizde Maps JavaScript API ve Places UI Kit'i etkinleştirin.
Başlamadan önce Maps JavaScript API'yi yüklediğinizden ve gerekli kitaplıkları içe aktardığınızdan emin olun. Bu belgede ayrıca HTML, CSS ve JavaScript dahil olmak üzere web geliştirme konusunda bilgi sahibi olduğunuz varsayılır.
Sayfaya harita ekleme
İlk adım, sayfanıza bir harita eklemektir. Bu harita, PlaceSearchElement sonuçlarını seçilebilir raptiyeler olarak göstermek için kullanılır.
Bir sayfaya harita eklemenin iki yolu vardır:
gmp-mapHTML web bileşeni kullanma- JavaScript kullanma
Bu sayfadaki kod snippet'leri, JavaScript eşlemesi kullanılarak oluşturulmuştur.
Harita, kullanıcının etrafında arama yapmasını istediğiniz bir konumu (ör. otel) merkeze alabilir veya haritayı ortalamak için kullanıcının mevcut konumunu soracak şekilde başlatılabilir. Bu belgede, aramayı sabitlemek için sabit bir konum kullanacağız.
Otel gibi sabit bir konumun yakınındaki yerleri görselleştiriyorsanız bu yeri temsil etmek için haritaya işaretçi yerleştirin. Örneğin:
Harita, San Francisco'yu merkeze alır ve yakınında arama yaptığımız yeri temsil eden mavi bir raptiye gösterir. Raptiye rengi PinElement kullanılarak özelleştirildi.
Harita Türü kontrolü, kullanıcı arayüzünde gizlendi.
PlaceSearchElement ayarlarını yapın
Şimdi PlaceSearchElement öğesini görüntülemek için HTML ve CSS'yi ayarlayın. Bu örnekte öğe, haritanın sol tarafında kaydırılır ancak uygulamanıza uygun farklı düzenler deneyebilirsiniz.
PlaceSearchElement, bildirim temelli bir yaklaşım kullanır. Arama türünü tamamen JavaScript'te yapılandırmak yerine, ana <gmp-place-search> bileşeninin içine <gmp-place-nearby-search-request> gibi bir istek öğesi yerleştirerek doğrudan HTML'nizde tanımlarsınız.
HTML kodunuzda bir <gmp-place-search> öğesi başlatın. Sonuçlarda tıklama etkinliklerini etkinleştirmek için selectable özelliğini kullanın. İçine bir <gmp-place-nearby-search-request> ekleyerek bu öğenin Yakında Arama için kullanılacağını belirtin.
<gmp-place-search selectable>
<gmp-place-nearby-search-request>
</gmp-place-nearby-search-request>
</gmp-place-search>
İlk aramayı yapmak ve sonuçları görüntülemek için JavaScript kullanarak iç içe yerleştirilmiş istek öğesine referans alır ve özelliklerini ayarlarız. Önceki adımda elde edilen işaretçi konumunu merkez noktası olarak kullanarak locationRestriction olarak kullanılacak bir Circle başlatın. Ardından, aramayı tetiklemek için istek öğesinde locationRestriction ve includedPrimaryTypes özelliklerini ayarlayın.
Bunun için kod snippet'i aşağıdaki gibidir:
// Get references to the Place Search and its nested request element
const placeSearchElement = document.querySelector("gmp-place-search");
const placeSearchRequestElement = document.querySelector("gmp-place-nearby-search-request");
// Define the location restriction for the search
const circleRestriction = new Circle({
center: marker.position,
radius: 500
});
// Set the properties on the request element to perform an initial search for restaurants.
placeSearchRequestElement.locationRestriction = circleRestriction;
placeSearchRequestElement.includedPrimaryTypes = ['restaurant'];
Uygulamanın bu aşamada nasıl görünebileceğine dair bir örnek aşağıda verilmiştir:
Kullanıcının arama yapmasına izin ver
PlaceSearchElement iki arama seçeneği sunar:
<gmp-place-nearby-search-request>: Yerler Yakında Arama'dan Yer türlerini kullanarak arama sonuçlarını oluşturun.<gmp-place-text-search-request>: "San Francisco'da suşi" gibi serbest metin girişi kullanarak Places Text Search'ten arama sonuçlarını oluşturun.
Bunlar, <gmp-place-search> içindeki iç içe yerleştirilmiş öğelerdir. Ardından, JavaScript kullanarak bu iç içe yerleştirilmiş istek öğesinde özellikleri ayarlayarak aramaları tetiklersiniz.
Bu bölümde her iki yöntemin de uygulanması açıklanmaktadır.
Yakında arama
Kullanıcıların yakında arama yapmasına izin vermek için öncelikle Yer Türü seçebilecekleri bir kullanıcı arayüzü öğesi gerekir. Uygulamanız için en uygun seçim yöntemini belirleyin. Örneğin, yer türü seçeneklerinin yer aldığı bir açılır liste kullanabilirsiniz.
Kullanım alanınızla alakalı türlerin bir alt kümesini seçmeniz önerilir.
Örneğin, turistlere bir otelin yakınında neler olduğunu gösteren bir uygulama geliştiriyorsanız bakery, coffee_shop, museum, restaurant ve tourist_attraction seçeneklerini belirleyebilirsiniz.
HTML'niz, içinde <gmp-place-nearby-search-request> yerleştirilmiş <gmp-place-search> öğesini içermelidir.
<gmp-place-search selectable>
<gmp-place-nearby-search-request>
</gmp-place-nearby-search-request>
</gmp-place-search>
Ardından, yer türü seçicinizde change etkinliği için bir JavaScript dinleyici oluşturun. Bu dinleyici, <gmp-place-nearby-search-request> öğesinin özelliklerini güncelleyen bir işlevi çağırır. Bu işlev, otomatik olarak yeni bir arama tetikler ve listeyi günceller.
// Get a reference to the nested request element
const placeSearchRequestElement = document.querySelector('gmp-place-nearby-search-request');
// Function to update the place search based on the selected type
function updatePlaceList() {
const selectedType = placeTypeSelect.value;
if (!selectedType) {
// If no type is selected, don't perform a search.
// You could optionally hide the list or clear previous results here.
placeSearchElement.style.display = 'none';
return;
}
placeSearchElement.style.display = 'block';
// Set properties on the request element to trigger a new search
placeSearchRequestElement.locationRestriction = searchCircle;
placeSearchRequestElement.maxResultCount = 8;
placeSearchRequestElement.includedPrimaryTypes = [selectedType];
}
Kurulum adımındaki searchCircle, locationRestriction için de kullanılır. includedPrimaryTypes özelliği, kullanıcının seçimindeki değere ayarlanır. Sonuç sayısını sınırlamak için isteğe bağlı bir maxResultCount da ayarlanır.
Metin arayın
Metin aramayı etkinleştirmek için HTML yapılandırmanızın değişmesi gerekir. Yakında arama isteği yerine bir <gmp-place-text-search-request> öğesi yerleştirirsiniz.
<gmp-place-search selectable>
<gmp-place-text-search-request>
</gmp-place-text-search-request>
</gmp-place-search>
Kullanıcı arayüzünüze bir metin girişi ve arama düğmesi ekleyin. Düğmenin click etkinliği için
bir JavaScript dinleyicisi oluşturun. Etkinlik işleyici, kullanıcının girişini alır ve aramayı gerçekleştirmek için <gmp-place-text-search-request> öğesinin özelliklerini günceller.
// Get a reference to the text search request element
const placeTextSearchRequestElement = document.querySelector('gmp-place-text-search-request');
const textSearchInput = document.getElementById('textSearchInput');
const textSearchButton = document.getElementById('textSearchButton');
textSearchButton.addEventListener('click', performTextSearch);
function performTextSearch() {
const query = textSearchInput.value.trim();
if (!query) {
console.log("Search query is empty.");
return;
}
// Set properties on the request element to trigger a new search
placeTextSearchRequestElement.textQuery = query;
placeTextSearchRequestElement.locationBias = map.getBounds();
placeTextSearchRequestElement.maxResultCount = 8;
}
Burada, textQuery özelliğini kullanıcının girişiyle ayarlıyoruz. Ayrıca, mevcut harita sınırlarını kullanan bir locationBias de sağlarız. Bu, API'ye sonuçları kesin olarak sınırlamadan bu alandaki sonuçları tercih etmesini söyler. İsteğe bağlı bir maxResultCount, döndürülen sonuç sayısını sınırlar.
Yer raptiyelerini ve ayrıntılarını gösterme
Artık uygulama, yer araması yapabilir ve öğeyi doldurabilir. Bir sonraki adımda, işlevini şu şekilde geliştireceğiz:
PlaceSearchElementiçinde doldurulan her yer için haritada raptiyeler gösteriliyor.- Kullanıcının, belirli bir yer hakkında daha fazla ayrıntı görmek için raptiyeyi veya
PlaceSearchElementiçindeki yeri tıklamasına olanak tanır.
Uygulamanın yakında arama veya metin arama kullanması fark etmeksizin bu adımın ilkesi aynıdır.
Öncelikle, yer işaretlerini depolamak için JavaScript kodunuza bir genel değişken ekleyin. Bu sayede, arama değiştiğinde bunları kaldırabilir ve tıklama etkinliklerini işleyebilirsiniz.
let markers = {};
Haritaya işaretçi eklemek için bir işlev oluşturun. Bu işlev, yeni arama sonuçları yüklendiğinde çağrılır. Bu işlem:
- Haritadaki mevcut yer işaretlerini kaldırın.
PlaceSearchElementsonuçları arasında gezinip her biri için bir işaretçi ekleyin.- Haritanın sınırlarını, tüm yeni işaretçiler görünecek şekilde ayarlayın.
Arama sonuçlarının ne zaman kullanılabilir olduğunu dinlemek için <gmp-place-search> öğesine bir gmp-load etkinlik işleyici ekleyin. Bu etkinlik, arama tamamlandıktan
ve sonuçlar oluşturulduktan sonra tetiklenir.
Dinleyiciyi arama işlevimizin (ör. updatePlaceList) içine ekleyeceğiz ve yalnızca mevcut aramanın sonuçları için tetiklendiğinden emin olmak amacıyla { once: true } seçeneğini kullanacağız.
// In your search function, after setting the request properties:
placeSearchElement.addEventListener('gmp-load', addMarkers, { once: true });
addMarkers işlevi şu şekildedir:
async function addMarkers() {
const { LatLngBounds } = await google.maps.importLibrary("core");
const bounds = new LatLngBounds();
if (placeSearchElement.places.length > 0) {
// Remove existing markers
for (const m in markers) {
markers[m].map = null;
}
markers = {};
// Loop through each place from the search results
// and add a marker for each one.
for (const place of placeSearchElement.places) {
const marker = new google.maps.marker.AdvancedMarkerElement({
map: map,
position: place.location,
});
markers[place.id] = marker;
bounds.extend(place.location);
marker.collisionBehavior = google.maps.CollisionBehavior.REQUIRED_AND_HIDES_OPTIONAL;
// Add a click listener for each marker.
marker.addListener('gmp-click', (event) => {
// The main logic for showing details will go here.
});
}
// Position the map to display all markers.
map.setCenter(bounds.getCenter());
map.fitBounds(bounds);
}
}
Bu adım tamamlandıktan sonra uygulama aşağıdaki gibi görünür ve PlaceSearchElement tarafından döndürülen her yer için işaretçi gösterebilir:
Haritada işaretçilerimiz olduğuna göre son adım, Yer Ayrıntıları Öğesi tarafından sağlanan yer ayrıntılarını içeren bir bilgi penceresi göstermek için işaretçi ve öğe tıklama etkinliklerini işlemektir. Bu örnekte Yer Ayrıntıları En Yüksek Öğe'yi kullanacağız.
Yer Ayrıntıları En Yüksek Öğesi HTML'sini kodunuza ekleyin. Örneğin:
<gmp-place-details-compact orientation="vertical" style="display: none;">
<gmp-place-all-content></gmp-place-all-content>
<gmp-place-attribution light-scheme-color="gray" dark-scheme-color="white"></gmp-place-attribution>
</gmp-place-details-compact>
style, display: none olarak ayarlandı. Gerekli olana kadar görünmez.
gmp-place-all-content, tüm öğe içeriğini oluşturmak için iletilir. Hangi içeriğin oluşturulacağını seçmek için Place Details Compact Element (Yer Ayrıntıları Kompakt Öğesi) dokümanına bakın.
JavaScript'te, Yer Ayrıntıları Compact öğesine referans tutacak bir genel değişken oluşturun ve bu değişkeni başlatma kodunuzda doldurun. Örneğin:
let placeDetailsElement;
...
placeDetailsElement = document.querySelector('gmp-place-details-compact');
addMarkers işlevinde her bir işaretçiye gmp-click etkinlik işleyici ekleyin ve mevcut işaretçinin yer kimliğini ileterek yer ayrıntılarını gösterecek şekilde Place Details Compact Element'i yapılandırın.
Bu işlem tamamlandıktan sonra, işaretçiye sabitlenmiş Yer Ayrıntıları Kompakt Öğesi'ni görüntülemek için bir bilgi penceresi açılır.
Son olarak, harita seçilen yerin görüntü alanına göre konumlandırılarak görünür hale getirilir.
async function addMarkers() {
...
marker.addListener('gmp-click', (event) => {
//Set up Place Details Compact Widget
placeDetailsElement.style.display = "block";
// Remove any existing place request element
const existingPlaceRequest = placeDetailsElement.querySelector('gmp-place-details-place-request');
if (existingPlaceRequest) {
existingPlaceRequest.remove();
}
// Create and configure the new place request element
const placeRequestElement = new google.maps.places.PlaceDetailsPlaceRequestElement({ place: place.id });
// Prepend the new place request element to the main widget
placeDetailsElement.prepend(placeRequestElement);
if (infoWindow.isOpen) {
infoWindow.close();
}
infoWindow.setOptions({
content: placeDetailsElement
});
infoWindow.open({
anchor: marker,
map: map
});
// Position the map to show the selected place
placeDetailsElement.addEventListener('gmp-load', () => {
map.fitBounds(place.viewport, { top: 500, left: 400 });
});
});
...
});
}
}
Kullanıcının, Yer Ayrıntıları Kompakt Öğesi'ni göstermek için Yer Listesi Öğesi'ndeki bir yeri tıklayabilmesini sağlamak istiyorsanız JavaScript koduna configureFromSearchNearbyRequest çağrısından sonra aşağıdakileri ekleyin.
placeSearchElement.addEventListener("gmp-select", ({ place }) => {
if (markers[place.id]) {
markers[place.id].click();
}
});
Bu adım tamamlandıktan sonra uygulama, Yer Listesi Öğesi'ni doldurmak için Yakında Arama veya Metin Arama'yı kullanabilir. Bu işlemin sonucunda haritada raptiyeler gösterilir. Bir raptiyeyi veya Yer Listesi öğesindeki bir yeri tıkladığınızda, Yer Ayrıntıları Kompakt öğesi tarafından sağlanan yer ayrıntılarını içeren bir bilgi penceresi gösterilir.
Uygulama aşağıdaki gibi görünür:
Sonuç
PlaceSearchElement, Place Details Compact Element ile birlikte kullanıldığında Google Maps Platform uygulamalarınıza zengin yer keşfi özellikleri eklemenin kolay bir yolunu sunar.
Kullanıcılarınızın hem yakındaki yerleri hem de metin aramalarını kullanarak yerleri bulup keşfetmesini sağlamak ve zengin yer ayrıntıları göstererek yer keşfi kullanım alanlarınızla etkileşimlerini artırmak için Places UI Kit'i hemen deneyin.
Katkıda bulunanlar
Henrik Valve | DevX Mühendisi