Yeni Yer Adı Otomatik Tamamlama'ya geçiş

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:

• locationBias
• locationRestriction
• AutocompleteSessionToken
• ComponentRestrictions

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)

Yerler 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 HTML input öğ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 veya locationRestriction seçeneğini kullanarak sınırları ayarlayın.
• id özelliğini (HTMLElement öğesinden devralınır) kullanarak PlaceAutocompleteElement öğ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,
  });
}

• Otomatik Yer Tamamlama widget'ı (Önizleme) dokümanları
• Otomatik Yer Tamamlama widget'ı örneği
• Yer Adı Otomatik Tamamlama Öğesi örneği
• PlaceAutocompleteElement sınıf referansı