Hedef
Kullanıcıların yakında arama veya metinle arama özelliklerini kullanarak yer bulmasına yardımcı olmak ve ilgi çekici yerleri keşfetme becerilerini geliştirmek için PlaceSearchElement'ı Google Haritalar ile nasıl entegre edeceğinizi öğrenin. Uygulamanızda gösterilen yerler hakkında daha fazla ayrıntı sağlamak için Yer Ayrıntıları Kompakt Öğesi'ni kullanın.
PlaceSearchElement nedir?
PlaceSearchElement, Maps JavaScript API'deki Places UI Kit'in bir parçasıdır. Bu, bir yer aramasının sonuçlarını doğrudan uygulamanızdaki liste biçiminde oluşturmaya yarayan bir HTML öğesidir. Bu öğe, Yakınımda Arama veya Metin Arama kullanılarak bulunan yerleri gösterme sürecini basitleştirir ve yer keşfi için sorunsuz bir kullanıcı deneyimi sağlar. Kullanıcı listeden bir yer seçtiğinde, genellikle bir 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, PlaceSearchElement simgesinin kullanımına dair bir örnek gösterilmektedir. Solda restoranların listesi (PlaceSearchElement) gösterilir. Bir restoran seçildiğinde, restoranın ayrıntıları haritadaki bir bilgi penceresinde görünür ve harita, restoranın konumuna göre ortalanır.
Yer Keşfi ile İlgili Kullanım Alanları
PlaceSearchElement'nın entegrasyonu, farklı sektörlerdeki çeşitli uygulamaları geliştirebilir:
- Seyahat ve Turizm: Turistlerin bir bölgedeki turistik yerleri, otelleri veya belirli yemek 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ına olanak tanıyı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ışı: Yer Keşfi'ni Uygulama
Bu bölümde, PlaceSearchElement'ı entegre ederek haritadaki yerleri keşfetme süreci açıklanmakta ve Places UI Kit ile etkileşim kurmaya yönelik kod snippet'leri yer almaktadır. Haritayı başlatmayı ve hem Yakındaki Arama hem de Metin Arama'yı uygulamayı öğrenin. Son olarak, kullanıcı haritada bir yerin raptiyesini tıkladığında bu yerle ilgili daha fazla ayrıntı göstermek için Yer Ayrıntıları öğesini kullanın.
Ön koşullar
Aşağıdaki belgeler hakkında bilgi sahibi olmanız önerilir:
PlaceSearchElement- Yakında Arama veya Metin Arama kullanılarak yerleri göstermek için kullanılır.- Yer Ayrıntıları Öğesi - Belirli bir yerin ayrıntılarını göstermek 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ğinizi ve gerekli kitaplıkları içe aktardığınızı doğrulayın. Bu belgede, HTML, CSS ve JavaScript dahil olmak üzere web geliştirme hakkında bilgi sahibi olduğunuz da varsayılır.
Sayfaya harita ekleme
İlk adım, sayfanıza harita eklemektir. Bu harita, PlaceSearchElement sonuçlarını seçilebilir raptiyeler olarak göstermek için kullanılır.
Sayfaya harita eklemenin iki yolu vardır:
gmp-mapHTML web bileşeni kullanma.- JavaScript kullanıyorsanız.
Bu sayfadaki kod snippet'leri, JavaScript haritası kullanılarak oluşturulmuştur.
Harita, kullanıcının etrafında arama yapmasını istediğiniz bir konuma (ör. otel) odaklanabilir 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 kullanılacaktır.
Sabit bir konumun (ör. otel) yakınındaki yerleri görselleştiriyorsanız bu yeri temsil etmek için haritaya bir işaretçi yerleştirin. Örneğin:
Harita, San Francisco'nun merkezinde yer alıyor. Yakınlarda arama yaptığımız yeri temsil eden mavi bir raptiye var. Raptiye rengi, PinElement kullanılarak özelleştirildi.
Harita Türü denetimi, kullanıcı arayüzünden 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ıyor ancak uygulamanıza uygun farklı düzenler deneyebilirsiniz.
PlaceSearchElement, bildirimsel bir yaklaşım kullanır. Tamamen JavaScript'te yapılandırmak yerine, <gmp-place-nearby-search-request> gibi bir istek öğesini ana <gmp-place-search> bileşeninin içine yerleştirerek arama türünü 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. Bu öğenin yakındaki cihazları arama için kullanılacağını belirtmek üzere içine bir <gmp-place-nearby-search-request> ekleyin.
<gmp-place-search selectable>
<gmp-place-nearby-search-request>
</gmp-place-nearby-search-request>
</gmp-place-search>
İlk aramayı yapmak ve sonuçları göstermek için JavaScript'i kullanarak iç içe yerleştirilmiş istek öğesine referans alır ve özelliklerini ayarlarız. Önceki adımdaki işaretçi konumunu odak noktası olarak kullanarak locationRestriction olarak kullanılacak bir daire başlatın. Ardından, aramayı tetiklemek için istek öğesinde locationRestriction ve includedPrimaryTypes özelliklerini ayarlayın.
Bunun 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 örneği aşağıda bulabilirsiniz:
Kullanıcının arama yapmasına izin ver
PlaceSearchElement simgesi iki arama seçeneği sunar:
<gmp-place-nearby-search-request>- Yer Türleri'ni kullanarak Yakında Arama'dan arama sonuçları oluşturun.<gmp-place-text-search-request>- "San Francisco'da suşi" gibi serbest metin girişi kullanarak Yerler Metin Arama'dan arama sonuçları oluşturun.
Bunlar, <gmp-place-search> öğesinin içindeki iç içe yerleştirilmiş öğelerdir. Daha sonra, JavaScript kullanarak bu iç içe yerleştirilmiş istek öğesinde özellikler ayarlayarak aramaları tetiklersiniz.
Bu bölümde, her iki yöntemin de nasıl uygulanacağı açıklanmaktadır.
Yakında arama
Kullanıcıların yakındaki yerleri aramasına izin vermek için öncelikle Yer Türü seçebilecekleri bir kullanıcı arayüzü öğesine ihtiyacınız vardır. Uygulamanız için en uygun seçim yöntemini belirleyin. Örneğin, yer türü seçenekleriyle doldurulmuş bir açılır liste.
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'i seçebilirsiniz.
HTML'niz, içine <gmp-place-nearby-search-request> öğesi yerleştirilmiş bir <gmp-place-search> öğesi 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 dinleyicisi 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 başlatır 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 aynı searchCircle, locationRestriction için kullanılır. includedPrimaryTypes özelliği, kullanıcının seçiminden alınan değere ayarlanır. Sonuç sayısını sınırlamak için isteğe bağlı bir maxResultCount de ayarlanır.
Metin arayın
Metin arama özelliğini etkinleştirmek için HTML yapılandırmanızın değiştirilmesi gerekir. Yakındaki 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 bir arama düğmesi ekleyin. Düğmenin click etkinliği için bir JavaScript işleyici 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ği kullanıcının girişiyle ayarlanır. Ayrıca, API'ye sonuçları kesin olarak sınırlamadan bu alan içinde tercih etmesini söyleyen, mevcut harita sınırlarını kullanan bir locationBias da sağlıyoruz. İsteğe bağlı bir maxResultCount, döndürülen sonuçların 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, aşağıdaki işlemleri yaparak işlevselliğini artıracağız:
PlaceSearchElementbölümünde doldurulan her yer için haritada raptiye gösterme.- Kullanıcının, belirli bir yer hakkında daha fazla ayrıntı göstermek için
PlaceSearchElementiçindeki bir pimi veya yeri tıklamasına izin verilir.
Uygulama, yakındaki arama veya metin araması kullanıyor olsa da bu adımın ilkesi aynıdır.
Öncelikle yer işaretlerini saklamak için JavaScript kodunuza genel bir 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ını tek tek inceleyin ve her biri için işaretçi ekleyin.- Tüm yeni işaretçilerin görünmesi için haritanın sınırlarını ayarlayın.
Arama sonuçlarının ne zaman kullanıma sunulduğunu dinlemek için gmp-load öğesine bir <gmp-place-search> etkinlik dinleyicisi ekleyin. Bu etkinlik, arama tamamlandıktan ve sonuçlar oluşturulduktan sonra tetiklenir.
Dinleyiciyi arama işlevimize (ör. updatePlaceList) ekleyip yalnızca geçerli aramanın sonuçları için tetiklendiğinden emin olmak üzere { 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 şekilde görünür:
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, PlaceSearchElement tarafından döndürülen her yer için işaretçiler gösterebilme özelliğiyle birlikte aşağıdaki gibi görünür:
Haritada işaretçiler 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ı 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. Gerekli olana kadar görünmez.
Tüm öğe içeriğini oluşturmak için gmp-place-all-content iletilir. Hangi içeriğin oluşturulacağını seçmek için Yer Ayrıntıları Kompakt Öğesi dokümanına bakın.
Yer Ayrıntıları Compact Element'e referans tutmak için JavaScript'te global bir değişken 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österecek şekilde Yer Ayrıntıları Compact öğesini yapılandırın.
Bu işlem tamamlandıktan sonra, işaretçiye sabitlenmiş Yer Ayrıntıları Compact Element'i görüntülemek için bir Bilgi Penceresi açılır.
Son olarak, harita seçilen yerin görünüm alanına göre konumlandırılır ve görünür hale gelir.
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ıklamasını sağlamak amacıyla configureFromSearchNearbyRequest çağrısından sonra JavaScript koduna 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ınlardaki Arama veya Metin Arama'yı kullanabilir. Bu işlemin sonuçları haritada raptiyelerle gösterilir. Bir raptiyeyi veya Yer Listesi Öğesi'ndeki 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, Yer Ayrıntıları Kompakt Öğesi ile birlikte Google Haritalar Platformu 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ını göstermek için Places UI Kit'i bugün deneyin. Böylece, kullanıcılarınızın yer keşfi kullanım alanlarınızla etkileşimini artırabilirsiniz.
Katkıda bulunanlar
Henrik Valve | DevX Engineer