Hedef
Kullanıcıların yakındaki arama veya metin arama özelliğini kullanarak yerleri bulmalarına yardımcı olmak ve önemli noktaları keşfetmelerini kolaylaştırmak için yer arama öğesini Google Haritalar'a nasıl entegre edeceğinizi öğrenin. Uygulamanızda gösterilen yerler hakkında daha fazla bilgi sağlamak için Yer Ayrıntıları Kompakt Öğesi'ni kullanın.
Yer arama öğesi nedir?
Yer arama öğesi, Maps JavaScript API'deki Yerler kullanıcı arayüzü paketinin bir parçasıdır. Bir yer aramasının sonuçlarını doğrudan uygulamanızda liste biçiminde oluşturan bir HTML öğesidir. Bu öğe, Yakındakiler Arama veya Metin Arama kullanılarak bulunan yerlerin gösterilme sürecini basitleştirerek yer keşfi için sorunsuz bir kullanıcı deneyimi sunar. Kullanıcı listeden bir yer seçtiğinde, genellikle bilgi penceresi ve yer ayrıntıları öğesini kullanarak bu yerin ayrıntılarını haritada gösterebilirsiniz.
Yer keşfini görselleştirme
Aşağıdaki resimde, Yer Arama Öğesi'nin işleyiş şekliyle ilgili bir örnek gösterilmektedir. Sol tarafta restoranların listesi gösterilir (Yer Arama Öğesi). Bir restoran seçildiğinde, restoranın ayrıntıları haritada bir bilgi penceresinde gösterilir ve harita, restoranın konumuna odaklanır.
Yer Keşfi'nin kullanım alanları
Yer arama öğesini entegre etmek, farklı sektörlerdeki çeşitli uygulamaları iyileştirebilir:
- Seyahat ve Turizm: Turistlerin bir bölgedeki turistik yerleri, otelleri veya belirli yemek türlerini aramaları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ülere elektrikli araç şarj istasyonları, benzin istasyonları veya belirli servis merkezlerini bulma konusunda yardımcı olun.
Çözüm iş akışı: Yer Keşfi'ni uygulama
Bu bölümde, harita üzerinde yerleri keşfetmek için Place Search Element'i entegre etme adımları adım adım açıklanmıştır. Bu adımlara Places UI Kit ile etkileşime geçmek için kullanılan kod snippet'leri de dahildir. Haritayı başlatmayı ve hem Yakındakiler Arama hem de Metin Arama işlevlerini uygulamayı ele alacağız. Son olarak, haritadaki raptiye tıklandığında belirli bir yer hakkında daha fazla ayrıntı göstermek için Yer Ayrıntıları öğesini kullanacağız.
Ön koşullar
Aşağıdaki dokümanları incelemeniz önerilir:
- Yer Arama Öğesi - Yakında Arama veya Metin Arama'yı kullanarak yerleri göstermek için kullanılır
- Yer Ayrıntıları Öğesi - Bir yerin ayrıntılarını görüntülemek için kullanılır
- Maps JavaScript API: Sayfanızda harita göstermek ve Yerler kullanıcı arayüzü kitini içe aktarmak için kullanılır.
Projenizde Maps JavaScript API ve Yerler Kullanıcı Arayüzü Kiti'ni etkinleştirin.
Başlamadan önce Maps JavaScript API'yi yüklediğinizden ve 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.
Sayfaya harita ekleme
İlk adım olarak sayfanıza bir harita ekleyin. Bu harita, yer arama öğesi sonuçlarını seçilebilir raptiyeler olarak görüntülemek için kullanılır.
Bir sayfaya harita eklemenin iki yolu vardır:
gmp-mapHTML web bileşeni kullanma- JavaScript'i kullanma
Bu sayfadaki kod snippet'leri bir JavaScript haritası kullanılarak oluşturulmuştur.
Harita, kullanıcının arama yapmasını istediğiniz bir konuma (ör. otel) odaklanabilir veya haritayı kullanıcının mevcut konumuna odaklayacak şekilde başlatılabilir. Bu doküman kapsamında, aramayı sabitlemek için sabit bir konum kullanacağız.
Sabit bir konumun (ör. otel) 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ınlarda aradığımız yeri mavi bir raptiyeyle gösterir. Raptiye rengi PinElement kullanılarak özelleştirilmiştir.
Harita Türü denetimi kullanıcı arayüzünden gizlendi.
Yer arama öğesini ayarlama
Artık HTML ve CSS'yi yer arama öğesini gösterecek şekilde ayarlayabiliriz. Bu örnekte, öğeyi haritanın sol tarafına yerleştireceğiz ancak uygulamanıza uygun farklı düzenler denemeniz önerilir.
HTML kodunuzda, yer arama öğesini barındıracak bir div oluşturun.
Bu içinde boş bir gmp-place-list başlatın.
Öğede tıklama etkinliklerini etkinleştirmek için selectable özelliğini gmp-place-list to ile kullanın.
<gmp-place-list selectable></gmp-place-list>
Bu aşamada, sonuçların doğru şekilde gösterilip gösterilmediğini test etmek için yer türü aramak üzere configureFromSearchNearbyRequest aracını kullanın.
Yer arama öğesini, bir yer aramasının sonuçlarını gösterecek şekilde yapılandırmak için JavaScript'i kullanın. Bir merkez noktası ve uygun bir yarıçap kullanarak locationRestriction olarak kullanılacak bir daire başlatın. Bu örnekte öğe, restaurant yer türü için arama yapacak şekilde yapılandırılmıştır ve önceki adımda ayarlanan işaretçi konumu, daire merkez noktası olarak kullanılır.
Bununla ilgili kod snippet'i aşağıdaki gibidir:
const placeListElement = document.querySelector("gmp-place-list");
const circleRestriction = new Circle({
center: marker.position,
radius: 500
});
placeListElement.configureFromSearchNearbyRequest({
locationRestriction: circleRestriction,
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
Yer arama öğesi iki arama seçeneği sunar:
configureFromSearchNearbyRequest: PlaceTypes özelliğini kullanarak Yakındaki Yerler aramasından arama sonuçlarını oluşturur.configureFromSearchByTextRequest: "San Francisco'da sushi" gibi bir serbest metin girişi kullanarak Yerler metin aramasından arama sonuçlarını oluşturur.
Bu bölümde her iki yöntemin de uygulanması açıklanmaktadır.
Yakında arama
Kullanıcının, Yer Arama Öğesi'nin hangi Yer Türü'nü göstereceğini seçmesine olanak tanıyan bir kullanıcı arayüzü öğesi uygulayın. Kullanım alanınıza uygun bir alt küme seçmeniz önerilir. Örneğin, turistlere bir otelin yakınındaki yerleri göstermek için bir uygulama geliştiriyorsanız bakery, coffee_shop, museum, restaurant ve tourist_attraction seçeneklerini belirleyebilirsiniz. Uygulamanız için en uygun seçim yöntemini seçin (ör. çeşitli yer türleriyle doldurulmuş bir açılır liste).
Yer türü seçim kullanıcı arayüzünüzdeki değişiklik etkinliğini işlemek için bir JavaScript dinleyicisi oluşturun. İşleyiciyi, configureFromSearchNearbyRequest kullanarak seçilen yer türüne göre Yer Arama Öğesini güncellemek için bir işlev çağıracak şekilde yapılandırın.
Yer arama öğesini bir işlev kullanarak güncelleme örneği aşağıda verilmiştir:
// Function to update the place search
function updatePlaceList() {
const selectedType = placeTypeSelect.value;
if (!selectedType) {
console.warn("No place type selected.");
// Clear results or handle as needed
placeListElement.requestedResultTypes = [];
return;
}
placeListElement.configureFromSearchNearbyRequest({
locationRestriction: searchCircle,
maxResultCount: 8,
includedPrimaryTypes: [selectedType],
});
}
Önceki adımda ayarlanan aynı daire locationRestriction kullanılır. includedPrimaryTypes parametresi, kullanıcı arayüzünde seçilen değere göre ayarlanır.
Yer arama öğesinde döndürülen ve görüntülenen sonuç sayısını kısıtlamak için isteğe bağlı bir maxResultCount da ayarlanmıştır.
Metin arayın
Kullanıcılarınızın metin aramalarını girebileceği bir düğmeyle metin girişi ekleyin. Düğmedeki click etkinliğini işleyen bir JavaScript dinleyicisi oluşturun ve configureFromSearchByTextRequest kullanarak yer arama öğesini, girilen arama dizesini kullanarak arama yapacak şekilde yapılandırın.
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;
}
placeListElement.configureFromSearchByTextRequest({
textQuery: query,
locationRestriction: map.getBounds(),
maxResultCount: 8,
});
}
Bu örnekte, haritanın mevcut sınırları kullanılarak isteğe bağlı bir locationRestriction ayarlanır. Arama sorgusu, textQuery parametresi kullanılarak iletilir.
Yer arama öğesinde döndürülen ve görüntülenen sonuç sayısını kısıtlamak için isteğe bağlı bir maxResultCount da ayarlanmıştır.
Yer raptiyelerini ve ayrıntılarını gösterme
Artık uygulama, yer araması yapabilir ve öğeyi doldurabilir. Bir sonraki adımda, işlevini aşağıdaki şekilde geliştireceğiz:
- Yer arama öğesinde doldurulan her yer için haritada raptiye gösterme
- Kullanıcının, yer arama öğesindeki bir raptiyeyi veya yeri tıklayarak ilgili yer hakkında daha fazla ayrıntı göstermesine olanak tanır.
Bu adımın prensibi, uygulamada configureFromSearchNearbyRequest veya configureFromSearchByTextRequest kullanılıyor olsa da aynıdır. Bu örnekte configureFromSearchNearbyRequest değerini kullanacağız.
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 yer ayrıntılarını görüntülemek için tıklama etkinliklerini yönetebilirsiniz.
let markers = {};
Aşağıdakilere işlev ekleyebilirsiniz:
- Mevcut yer işaretçilerini kaldırın.
- Yer arama öğesi sonuçlarını sırayla inceleyin ve her biri için bir işaretçi ekleyin.
- Haritanın sınırlarını, tüm işaretçilerin görünür olacağı şekilde ayarlayın.
async function addMarkers() {
const { LatLngBounds } = await google.maps.importLibrary("core");
const bounds = new LatLngBounds();
if (placeListElement.places.length > 0) {
// Remove existing markers
for (m in markers) {
markers[m].map = null;
}
markers = {};
// Loop through each place in the Place Search Element
// Add a marker for each place
placeListElement.places.forEach((place) => {
let marker = new AdvancedMarkerElement({
map: map,
position: place.location,
});
markers[place.id] = marker;
bounds.extend(place.location);
marker.collisionBehavior = google.maps.CollisionBehavior.REQUIRED_AND_HIDES_OPTIONAL;
// Position the map to display all markers with the bounds
map.setCenter(bounds.getCenter());
map.fitBounds(bounds);
});
}
}
Son olarak, configureFromSearchNearbyRequest vaadi başarıyla çözüldüğünde yeni addMarkers() işlevini şu şekilde çağırın:
placeListElement.configureFromSearchNearbyRequest({
locationRestriction: searchCircle,
maxResultCount: 8,
includedPrimaryTypes: [selectedType],
}).then(addMarkers);
Bu adım tamamlandığında uygulama, Yer Arama Öğesi tarafından döndürülen her yer için işaretçi gösterme özelliğiyle aşağıdaki gibi görünür:
Haritaya işaretçiler ekledik. Son adımda, 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 ele alacağız. Bu örnekte Yer Ayrıntıları Kompakt Öğesi'ni kullanacağız.
Yer Ayrıntıları Kompakt Öğ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 ayarlanmıştır ve gerekli olana kadar görünmez.
gmp-place-all-content, tüm öğe içeriklerini oluşturmak için iletilir. Oluşturulacak içeriği seçmek için Yer Ayrıntıları Kompakt Öğesi dokümanlarına bakın.
Yer Ayrıntıları Kompakt Öğesi'ne referans verecek bir JavaScript global değişkeni oluşturun ve bunu başlatma kodunuzda doldurun. Örneğin:
let placeDetailsElement;
…
placeDetailsElement = document.querySelector('gmp-place-details-compact');
addMarkers işlevinde, her işaretçiye bir gmp-click etkinlik dinleyicisi ekleyin ve mevcut işaretçinin yer kimliğini ileterek yer ayrıntılarını göstermek için Yer Ayrıntıları Kompakt Öğesini yapılandırın.
Bu işlem tamamlandıktan sonra, işaretçiye sabitlenmiş yer ayrıntıları kompakt öğesini görüntülemek için bir bilgi penceresi açılır.
Son olarak, harita seçilen yerin görüntüleme alanına yerleştirilerek 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 Listesi Öğesi'ndeki bir yeri tıklayarak Yer Ayrıntıları Kompakt Öğesi'ni göstermesini sağlamak için configureFromSearchNearbyRequest çağrısından sonra JavaScript koduna aşağıdakileri ekleyin.
placeListElement.addEventListener("gmp-placeselect", ({ place }) => {
markers[place.id].click();
});
Bu adım tamamlandıktan sonra uygulama, yer listesi öğesini doldurmak için Yakındakiler araması veya metin araması yapabilir. Bu işlemin sonuçları haritada raptiyelerle gösterilir. Yer Listesi Öğesi'ndeki bir raptiyeyi veya 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ç
Yer Arama Öğesi, Yer Ayrıntıları Kompakt Öğesi ile birlikte Google Haritalar Platformu uygulamalarınıza zengin yer keşfi özellikleri eklemenin basit bir yolunu sunar.
Kullanıcılarınızın hem yakınlık hem de metin aramalarını kullanarak yerleri bulup keşfetmelerini sağlamak ve yer keşfi kullanım alanlarınızla etkileşimlerini artırarak zengin yer ayrıntıları göstermek için Places UI Kit'i hemen deneyin.
Katkıda bulunanlar
Henrik Valve | DevX Mühendisi