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

Avrupa Ekonomik Alanı (AEA) geliştiricileri

Yer Otomatik Tamamlama, Maps JavaScript API'deki Yerler kitaplığının bir özelliğidir. Uygulamalarınıza Google Haritalar arama alanının türüne göre arama davranışını kazandırmak için otomatik tamamlama özelliğini kullanabilirsiniz.

Bu sayfada, eski ve yeni yer otomatik tamamlama özellikleri arasındaki farklar açıklanmaktadır. Her iki sürümde de otomatik tamamlama özelliğini entegre etmenin iki genel yolu vardır:

Otomatik tamamlama programatik arayüzü

Aşağıdaki tabloda, Yer Otomatik Tamamlama Hizmeti (eski) ile Otomatik Tamamlama Verileri API'si (yeni) arasında programatik Otomatik Yer Tamamlama kullanımındaki bazı temel farklılıklar listelenmiştir:

PlacesService (Eski) Place (Yeni)
Places Autocomplete Service referansı Otomatik Tamamlama Verileri (yeni) referansı
AutocompletionRequest AutocompleteRequest
AutocompleteService.getPlacePredictions AutocompleteSuggestion.fetchAutocompleteSuggestions
AutocompletePrediction PlacePrediction
Yöntemler, sonuç nesnesini ve PlacesServiceStatus yanıtını işlemek için geri çağırma işlevinin kullanılmasını gerektirir. Promises kullanır ve eşzamansız olarak çalışır.
Yöntemler için PlacesServiceStatus kontrolü gerekir. Durum kontrolü gerekmez, standart hata işleme kullanılabilir. Daha fazla bilgi
Yer verileri alanları, Autocomplete örneği oluşturulduğunda seçenek olarak ayarlanır. Yer verileri alanları, fetchFields() çağrıldığında daha sonra ayarlanır.
Sorgu tahminleri desteklenir (yalnızca SearchBox). Sorgu tahminleri Autocomplete sınıfında kullanılamaz.
Yer türleri ve yer verileri alanlarından oluşan sabit bir grupla sınırlıdır. Daha fazla yer türü ve yer verisi alanına erişim.

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 yer hizmeti ile yer sınıfı arasındaki farkları göstermek amacıyla otomatik tamamlama kodları karşılaştırılmaktadır.

Otomatik tamamlama tahminlerini alma (eski)

Eski Places Service, Autocomplete sınıfının sunduğundan daha fazla kullanıcı arayüzü kontrolü için otomatik tamamlama tahminlerini programatik olarak almanıza olanak tanır. Aşağıdaki örnekte, "par" için tek bir istekte bulunulur. Bu istekte, giriş değerini ve tahmini yönlendirmek için bir dizi sınırı içeren bir AutocompletionRequest bulunur. Örnek, AutocompletePrediction örneklerinin bir listesini döndürür ve her birinin açıklamasını gösterir. Örnek işlev, bir oturum jetonu da oluşturur ve bunu 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 tamamlama tahminlerini alma (yeni)

Yeni Place sınıfı, PlaceAutocompleteElement sınıfının sunduğundan daha fazla kullanıcı arayüzü kontrolü için otomatik tamamlama tahminlerini programatik olarak almanıza da olanak tanır. Aşağıdaki örnekte, "par" için tek bir istekte bulunulur. Bu istekte, giriş değeri ve tahmini yönlendirmek için bir dizi sınır içeren bir AutocompleteRequest bulunur. Örnek, placePrediction örneklerinin listesini döndürür ve her birinin açıklamasını gösterir. Örnek işlev, bir oturum jetonu da oluşturur ve bunu 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}`
}

Yer Adı Otomatik Tamamlama widget'ı

Aşağıdaki tabloda, Yerler hizmeti (eski) ile Yer sınıfı (yeni) arasında otomatik tamamlama widget'larının kullanımındaki bazı temel farklılıklar listelenmiştir:

Places Service (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, tahmin listesi logosu ve yer tahminleri bölgesel yerelleştirmeyi destekler.
Widget, aramayı belirtilen sınırlar içinde tutmak (önyargı) için setBounds() veya autocomplete.bindTo() ve sonuçları belirtilen sınırlar içinde tutmak için strictBounds kullanır. Widget, sonuçları belirtilen sınırlar içinde tutmak için locationBias özelliğini, aramayı belirtilen sınırlar içinde tutmak 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.
Kullanıcılar, widget'ı kullanırken geçerli olmayan şeyler (ör. "bisneyland") isteyebilir. 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 isteklerin işlenmesine 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çenek olarak ayarlanır. Yer verileri alanları, kullanıcı seçim yaptığında ayarlanır ve fetchFields() çağrılır.
Yer türleri ve yer verileri alanlarından oluşan sabit bir grupla sınırlıdır. Daha fazla yer türü ve yer verisi alanına erişim.

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 kodları karşılaştırılmaktadır.

Yer Adı Otomatik Tamamlama Widget'ı (eski)

Places Service, Autocomplete ve SearchBox sınıflarını kullanarak ekleyebileceğiniz iki tür otomatik tamamlama widget'ı sunar. Her tür widget, haritaya harita kontrolü olarak eklenebilir veya doğrudan bir web sayfasına yerleştirilebilir. Aşağıdaki kod örneğinde, Autocomplete widget'ının harita kontrolü olarak nasıl yerleştirileceği gösterilmektedir.

  • Autocomplete widget oluşturucusu iki bağımsız değişken alır:
    • text türünde 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 argümanı.
  • 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 verileri 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 Widget'ı (Yeni)

Yer sınıfı, HTMLElement alt sınıfı olan PlaceAutocompleteElement sunar. Bu alt sınıf, harita kontrolü olarak haritaya eklenebilen veya doğrudan bir web sayfasına yerleştirilebilen bir kullanıcı arayüzü bileşeni sağlar. Aşağıdaki kod örneğinde, PlaceAutocompleteElement widget'ının harita kontrolü olarak nasıl yerleştirileceği gösterilmektedir.

Yer Otomatik Tamamlama Widget'ı aşağıdaki şekillerde iyileştirildi:

  • Autocomplete widget'ı kullanıcı arayüzü, metin girişi yer tutucusu, tahmin listesi logosu ve yer tahminleri için bölgesel yerelleştirmeyi (sağdan sola yazılan diller dahil) destekler.
  • Ekran okuyucular ve klavye etkileşimi desteği 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 farklar şunlardır:

  • PlaceAutocompleteElement kendi giriş alanını sağlar ve HTML veya JavaScript kullanılarak doğrudan sayfaya eklenir (mevcut bir giriş öğesi sağlanmak yerine).
  • Sorgu tahminleri Autocomplete sınıfında kullanılamaz.
  • PlaceAutocompleteElement, PlaceAutocompleteElementOptions kullanılarak oluşturulur.
    • Yer verileri alanları, seçim sırasında (fetchFields() çağrıldığında) belirtilir.
  • locationBounds veya locationRestriction seçeneğini kullanarak sınırlar belirleyin.
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-select listener, and display the results on the map.
  placeAutocomplete.addEventListener("gmp-select", async ( place ) => {
    const place = event.placePrediction.toPlace();
    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,
  });
}