Otomatik yer tamamlama, Maps JavaScript API'deki Yerler kitaplığının bir özelliğidir. Uygulamalarınıza Google Haritalar arama alanının önceden yazmayla arama davranışını kazandırmak için otomatik tamamlamayı kullanabilirsiniz.
Bu sayfada, eski ve yeni yer otomatik tamamlama özellikleri arasındaki farklar açıklanmaktadır. Her iki sürümde de otomatik tamamlamayı entegre etmenin iki genel yolu vardır:
- Programatik arayüz: Otomatik tamamlama deneyimi üzerinde daha fazla özelleştirme ve kontrol isteyen geliştiriciler için.
- Yer Otomatik Tamamlama widget'ı: Bir haritaya veya web sayfasına yerleştirilebilen bir arama çubuğudur.
Otomatik tamamlama programatik arayüzü
Aşağıdaki tabloda, programatik Yer Otomatik Tamamlama'nın Yerler Otomatik Tamamlama Hizmeti (eski) ile Otomatik Tamamlama Veri API'si (yeni) arasındaki temel farklılıklardan bazıları listelenmiştir:
PlacesService (Eski) |
Place (Yeni) |
---|---|
Yerler Otomatik Tamamlama Hizmeti referansı | Otomatik Tamamlama Verileri (yeni) referansı |
AutocompletionRequest |
AutocompleteRequest |
AutocompleteService.getPlacePredictions |
AutocompleteSuggestion.fetchAutocompleteSuggestions |
AutocompletePrediction |
PlacePrediction |
Yöntemler, sonuçlar nesnesini ve PlacesServiceStatus yanıtını işlemek için geri çağırma işlevinin kullanılmasını gerektirir. |
Promise'leri kullanır ve eşzamansız olarak çalışır. |
Yöntemler için PlacesServiceStatus kontrolü gerekir. |
Zorunlu durum kontrolü yoktur, standart hata işleme kullanılabilir. |
Yer verileri alanları, Autocomplete örneği oluşturulurken seçenek olarak ayarlanır. |
Yer veri alanları daha sonra fetchFields() çağrıldığında ayarlanır. |
Sorgu tahminleri desteklenir (yalnızca SearchBox ). |
Sorgu tahminleri Autocomplete sınıfında kullanılamaz. |
Sabit bir yer türü ve yer veri alanı kümesiyle sınırlıdır. | Genişletilmiş bir yer türü ve yer verisi alanı seçimine erişme |
Aşağıdakiler hem eski hem de yeni Autocomplete API'leri tarafından kullanılır:
Kod karşılaştırması (programatik)
Bu bölümde, programatik arayüzler için Places Hizmeti ile Place sınıfı arasındaki farkları göstermek amacıyla otomatik tamamlama kodu karşılaştırılmaktadır.
Otomatik tamamlama tahminlerini alma (eski)
Eski Places Hizmeti, kullanıcı arayüzü üzerinde Autocomplete
sınıfının sunduğundan daha fazla kontrol sahibi olmak için otomatik tamamlama tahminlerini programatik olarak almanıza olanak tanır.
Aşağıdaki örnekte, giriş değerinden ve tahmini önyargılı hale getirmek için bir dizi sınırdan oluşan bir AutocompletionRequest
ile "par" için tek bir istek gönderilmektedir. Örnek, AutocompletePrediction
örneklerinin listesini döndürür ve her birinin açıklamasını gösterir. Örnek işlev ayrıca bir oturum jetonu oluşturur ve isteğe uygular.
function init() {
const placeInfo = document.getElementById("prediction");
const service = new google.maps.places.AutocompleteService();
const placesService = new google.maps.places.PlacesService(placeInfo);
var sessionToken = new google.maps.places.AutocompleteSessionToken();
// Define request options.
let request = {
input: "par",
sessionToken: sessionToken,
bounds: {
west: -122.44,
north: 37.8,
east: -122.39,
south: 37.78,
},
}
// Display the query string.
const title = document.getElementById("title");
title.appendChild(
document.createTextNode('Place predictions for "' + request.input + '":'),
);
// Perform the query and display the results.
const displaySuggestions = function (predictions, status) {
// Check the status of the Places Service.
if (status != google.maps.places.PlacesServiceStatus.OK || !predictions) {
alert(status);
return;
}
predictions.forEach((prediction) => {
const li = document.createElement("li");
li.appendChild(document.createTextNode(prediction.description));
document.getElementById("results").appendChild(li);
});
const placeRequest = {
placeId: predictions[0].place_id,
fields: ["name", "formatted_address"],
};
placesService.getDetails(placeRequest, (place, status) => {
if (status == google.maps.places.PlacesServiceStatus.OK && place) {
placeInfo.textContent = `
First predicted place: ${place.name} at ${place.formatted_address}`
}
});
};
// Show the results of the query.
service.getPlacePredictions(request, displaySuggestions);
}
- Otomatik Yer Tamamlama Hizmeti tahminlerini programatik olarak alma
- Yer Adı Otomatik Tamamlama örneği
- Oturum jetonları
AutocompletionRequest
referansıAutocompletePrediction
referansı
Otomatik tamamlama tahminlerini alma (yeni)
Yeni Place sınıfı, kullanıcı arayüzü üzerinde PlaceAutocompleteElement
sınıfının sunduğundan daha fazla kontrol sahibi olmak için otomatik tamamlama tahminlerini programatik olarak almanıza da olanak tanır.
Aşağıdaki örnekte, giriş değerinden ve tahmini önyargılı hale getirmek için bir dizi sınırdan oluşan bir AutocompleteRequest
ile "par" için tek bir istek gönderilmektedir. Örnek, placePrediction
örneklerini döndürür ve her birinin açıklamasını gösterir. Örnek işlev ayrıca bir oturum jetonu oluşturur ve isteğe uygular.
async function init() {
let sessionToken = new google.maps.places.AutocompleteSessionToken();
// Define request options.
let request = {
input: "par",
sessionToken: sessionToken,
locationBias: {
west: -122.44,
north: 37.8,
east: -122.39,
south: 37.78,
},
};
// Display the query string.
const title = document.getElementById("title");
title.appendChild(
document.createTextNode('Place predictions for "' + request.input + '":'),
);
// Perform the query and display the results.
const { suggestions } =
await google.maps.places.AutocompleteSuggestion.fetchAutocompleteSuggestions(request);
const resultsElement = document.getElementById("results");
for (let suggestion of suggestions) {
const placePrediction = suggestion.placePrediction;
const listItem = document.createElement("li");
listItem.appendChild(
document.createTextNode(placePrediction.text.text),
);
resultsElement.appendChild(listItem);
}
// Show the first predicted place.
let place = suggestions[0].placePrediction.toPlace();
await place.fetchFields({
fields: ["displayName", "formattedAddress"],
});
const placeInfo = document.getElementById("prediction");
placeInfo.textContent = `
First predicted place: ${place.displayName} at ${place.formattedAddress}`
}
- Place Autocomplete Data API
- Otomatik Yer Tamamlama Veri Tahminleri örneği
- Yer Otomatik Tamamlama Veri Oturumları örneği
- Oturum jetonları
AutocompleteRequest
arayüz referansıAutocompleteSuggestion
sınıf referansıPlacePrediction
sınıf referansı
Yer adı otomatik tamamlama widget'ını yerleştirme
Aşağıdaki tabloda, Places hizmeti (eski) ile Place sınıfı (yeni) arasındaki otomatik tamamlama widget'larının kullanımındaki temel farklılıklardan bazıları listelenmiştir:
Yerler Hizmeti (Eski) | Yer (Yeni) |
---|---|
Yer tahminleri için Autocomplete sınıfı
|
Yer tahminleri için PlaceAutocompleteElement sınıfı
|
Sorgu tahminleri için SearchBox sınıfı |
Sorgu tahminleri Autocomplete sınıfında kullanılamaz.
|
Yalnızca varsayılan giriş yer tutucu metni yerelleştirilir. | Metin girişi yer tutucusu, tahminler listesi logosu ve yer tahminleri bölgesel yerelleştirmeyi destekler. |
Widget, aramayı belirtilen sınırlarla kısıtlamak (yönlendirmek) için
setBounds() veya autocomplete.bindTo()
ve sonuçları belirtilen sınırlarla kısıtlamak için
strictBounds kullanır.
|
Widget, sonuçları belirtilen sınırlara göre yönlendirmek için locationBias özelliğini, aramayı belirtilen sınırlarla kısıtlamak için ise locationRestriction özelliğini kullanır.
|
Widget'lar yalnızca standart bir HTML giriş öğesi kullanılarak entegre edilebilir. | Widget, standart bir HTML giriş öğesi veya gmp-place-autocomplete öğesi kullanılarak entegre edilebilir. |
Widget kullanılırken kullanıcıların geçerli olmayabilecek şeyler (ör. "bisneyland") istemesi mümkündür. Bu durum açıkça ele alınmalıdır. | Widget yalnızca sağlanan önerilerle ilgili sonuçlar döndürür ve rastgele değerler için istek gönderemez. Bu nedenle, geçersiz olabilecek istekleri işlemeye gerek yoktur. |
Eski
PlaceResult örneğini döndürür. |
Place örneğini döndürür. |
Yer verileri alanları, Autocomplete nesnesi için seçenekler olarak ayarlanır. |
Yer verileri alanları, kullanıcı bir seçim yaptığında ve fetchFields() çağrıldığında ayarlanır. |
Sabit bir yer türü ve yer veri alanı kümesiyle sınırlıdır. | Genişletilmiş bir yer türü ve yer verisi alanı seçimine erişme |
Kod karşılaştırması (widget'lar)
Bu bölümde, eski Yer Otomatik Tamamlama widget'ı ile yeni Yer Otomatik Tamamlama öğesi arasındaki farkları göstermek için otomatik tamamlama kodu karşılaştırılmaktadır.
Yer Adı Otomatik Tamamlama Widget'ı (eski)
Places Hizmeti, Autocomplete
ve SearchBox
sınıflarını kullanarak ekleyebileceğiniz iki tür otomatik tamamlama widget'ı sunar.
Her tür widget, harita kontrolü olarak haritaya eklenebilir veya doğrudan bir web sayfasına yerleştirilebilir. Aşağıdaki kod örneğinde, bir Autocomplete
widget'ının harita kontrolü olarak yerleştirilmesi gösterilmektedir.
Autocomplete
widget oluşturucusu iki bağımsız değişken alır:text
türündeki bir HTMLinput
öğesi. Bu, otomatik tamamlama hizmetinin izleyeceği ve sonuçlarını ekleyeceği giriş alanıdır.- Sorguyu kısıtlamak için daha fazla seçenek belirtebileceğiniz isteğe bağlı bir
AutocompleteOptions
bağımsız değişkeni.
- Sınırları ayarlamak için
Autocomplete
örneği,autocomplete.bindTo()
çağrılarak haritaya açıkça bağlanabilir. - Otomatik tamamlama seçeneklerinde yer veri alanlarını belirtin.
function initMap() {
const map = new google.maps.Map(document.getElementById("map"), {
center: { lat: 40.749933, lng: -73.98633 },
zoom: 13,
mapTypeControl: false,
});
const card = document.getElementById("pac-card");
const input = document.getElementById("pac-input");
const options = {
fields: ["formatted_address", "geometry", "name"],
strictBounds: false,
};
map.controls[google.maps.ControlPosition.TOP_LEFT].push(card);
const autocomplete = new google.maps.places.Autocomplete(input, options);
// Bind the map's bounds (viewport) property to the autocomplete object,
// so that the autocomplete requests use the current map bounds for the
// bounds option in the request.
autocomplete.bindTo("bounds", map);
const infowindow = new google.maps.InfoWindow();
const infowindowContent = document.getElementById("infowindow-content");
infowindow.setContent(infowindowContent);
const marker = new google.maps.Marker({
map,
anchorPoint: new google.maps.Point(0, -29),
});
autocomplete.addListener("place_changed", () => {
infowindow.close();
marker.setVisible(false);
const place = autocomplete.getPlace();
if (!place.geometry || !place.geometry.location) {
// User entered the name of a Place that was not suggested and
// pressed the Enter key, or the Place Details request failed.
window.alert("No details available for input: '" + place.name + "'");
return;
}
// If the place has a geometry, then present it on a map.
if (place.geometry.viewport) {
map.fitBounds(place.geometry.viewport);
} else {
map.setCenter(place.geometry.location);
map.setZoom(17);
}
marker.setPosition(place.geometry.location);
marker.setVisible(true);
infowindowContent.children["place-name"].textContent = place.name;
infowindowContent.children["place-address"].textContent =
place.formatted_address;
infowindow.open(map, marker);
});
}
- Yer Adı Otomatik Tamamlama dokümanları
- Otomatik Yer Tamamlama widget'ı örneği
- Yerler arama kutusu örneği
Autocomplete
sınıf referansı
Yer Adı Otomatik Tamamlama Widget'ı (Yeni)
Yer sınıfı, haritaya harita kontrolü olarak eklenebilen veya doğrudan bir web sayfasına yerleştirilebilen bir kullanıcı arayüzü bileşeni sağlayan HTMLElement
alt sınıfı olan PlaceAutocompleteElement
'i sunar. Aşağıdaki kod örneğinde, PlaceAutocompleteElement
widget'ının harita kontrolü olarak yerleştirilmesi gösterilmektedir.
Yer Otomatik Tamamlama Widget'ı aşağıdaki şekillerde iyileştirilmiştir:
- Otomatik Tamamlama widget'ı kullanıcı arayüzü, metin girişi yer tutucusu, tahminler listesi logosu ve yer tahminleri için bölgesel yerelleştirmeyi (RTL diller dahil) destekler.
- Ekran okuyucular ve klavye etkileşimi için destek de dahil olmak üzere gelişmiş erişilebilirlik.
- Otomatik tamamlama widget'ı, döndürülen nesnenin işlenmesini basitleştirmek için yeni
Place
sınıfını döndürür. - Mobil cihazlar ve küçük ekranlar için daha iyi destek.
- Daha iyi performans ve iyileştirilmiş grafik görünüm.
Uygulamadaki temel farklılıklar arasında şunlar bulunur:
- Sorgu tahminleri
Autocomplete
sınıfında kullanılamaz. PlaceAutocompleteElement
,PlaceAutocompleteElementOptions
kullanılarak oluşturulur.- Yer veri alanları, seçim sırasında (
fetchFields()
çağrıldığında) belirtilir. locationBounds
veyalocationRestriction
seçeneğini kullanarak sınırları ayarlayın.id
özelliğini (HTMLElement
öğesinden devralınır) kullanarakPlaceAutocompleteElement
öğesini bir HTML metin girişi öğesiyle ilişkilendirin.
let map;
let marker;
let infoWindow;
async function initMap() {
// Request needed libraries.
const [{ Map }, { AdvancedMarkerElement }] = await Promise.all([
google.maps.importLibrary("marker"),
google.maps.importLibrary("places"),
]);
// Initialize the map.
map = new google.maps.Map(document.getElementById("map"), {
center: { lat: 40.749933, lng: -73.98633 },
zoom: 13,
mapId: "4504f8b37365c3d0",
mapTypeControl: false,
});
const placeAutocomplete =
new google.maps.places.PlaceAutocompleteElement({
locationRestriction: map.getBounds(),
});
placeAutocomplete.id = "place-autocomplete-input";
const card = document.getElementById("place-autocomplete-card");
card.appendChild(placeAutocomplete);
map.controls[google.maps.ControlPosition.TOP_LEFT].push(card);
// Create the marker and infowindow.
marker = new google.maps.marker.AdvancedMarkerElement({
map,
});
infoWindow = new google.maps.InfoWindow({});
// Add the gmp-placeselect listener, and display the results on the map.
placeAutocomplete.addEventListener("gmp-placeselect", async ({ place }) => {
await place.fetchFields({
fields: ["displayName", "formattedAddress", "location"],
});
// If the place has a geometry, then present it on a map.
if (place.viewport) {
map.fitBounds(place.viewport);
} else {
map.setCenter(place.location);
map.setZoom(17);
}
let content =
'<div id="infowindow-content">' +
'<span id="place-displayname" class="title">' +
place.displayName +
'</span><br />' +
'<span id="place-address">' +
place.formattedAddress +
'</span>' +
'</div>';
updateInfoWindow(content, place.location);
marker.position = place.location;
});
}
// Helper function to create an info window.
function updateInfoWindow(content, center) {
infoWindow.setContent(content);
infoWindow.setPosition(center);
infoWindow.open({
map,
anchor: marker,
shouldFocus: false,
});
}