ย้ายข้อมูลไปยัง Place Autocomplete เวอร์ชันใหม่

นักพัฒนาซอฟต์แวร์ในเขตเศรษฐกิจยุโรป (EEA)

Place Autocomplete เป็นฟีเจอร์ของ Places Library ใน Maps JavaScript API คุณสามารถใช้การเติมข้อความอัตโนมัติเพื่อให้แอปพลิเคชันมีลักษณะการค้นหาแบบพิมพ์ล่วงหน้าของช่องค้นหา Google Maps

หน้านี้จะอธิบายความแตกต่างระหว่างฟีเจอร์การเติมข้อความอัตโนมัติของสถานที่แบบเดิมกับแบบใหม่ ในทั้ง 2 เวอร์ชัน การผสานรวมการเติมข้อความอัตโนมัติทำได้ 2 วิธีทั่วไป ดังนี้

อินเทอร์เฟซแบบเป็นโปรแกรมสำหรับการเติมข้อความอัตโนมัติ

ตารางต่อไปนี้แสดงความแตกต่างหลักบางประการในการใช้ Place Autocomplete แบบเป็นโปรแกรมระหว่าง Places Autocomplete Service (เดิม) กับ Autocomplete Data API (ใหม่)

PlacesService (เดิม) Place (ใหม่)
เอกสารอ้างอิงของ Place Autocomplete Service ข้อมูลอ้างอิงการเติมข้อความอัตโนมัติ (ใหม่)
AutocompletionRequest AutocompleteRequest
AutocompleteService.getPlacePredictions AutocompleteSuggestion.fetchAutocompleteSuggestions
AutocompletePrediction PlacePrediction
เมธอดต้องใช้การเรียกกลับเพื่อจัดการออบเจ็กต์ผลลัพธ์และ PlacesServiceStatus การตอบกลับ ใช้ Promise และทำงานแบบไม่พร้อมกัน
วิธีการต้องผ่านPlacesServiceStatusการตรวจสอบ ไม่ต้องตรวจสอบสถานะที่จำเป็น ใช้การจัดการข้อผิดพลาดมาตรฐานได้ ดูข้อมูลเพิ่มเติม
ระบบจะตั้งค่าฟิลด์ข้อมูลสถานที่เป็นตัวเลือกเมื่อสร้างAutocomplete อินสแตนซ์ ระบบจะตั้งค่าฟิลด์ข้อมูลสถานที่ในภายหลังเมื่อมีการเรียกใช้ fetchFields()
ระบบรองรับการคาดคะเนคำค้นหา (SearchBox เท่านั้น) การคาดการณ์การค้นหาไม่พร้อมใช้งานในคลาส Autocomplete
จำกัดไว้เฉพาะประเภทสถานที่ และฟิลด์ข้อมูลสถานที่ที่กำหนด สิทธิ์เข้าถึงประเภทสถานที่ และฟิลด์ข้อมูลสถานที่ที่เพิ่มขึ้น

ทั้ง API เดิมและ API ใหม่ของฟีเจอร์เติมข้อความอัตโนมัติใช้สิ่งต่อไปนี้

การเปรียบเทียบโค้ด (แบบเป็นโปรแกรม)

ส่วนนี้จะเปรียบเทียบโค้ดสำหรับการเติมข้อความอัตโนมัติเพื่อแสดงความแตกต่าง ระหว่างบริการ Places กับ คลาส Place สำหรับอินเทอร์เฟซแบบเป็นโปรแกรม

เรียกข้อมูลการคาดคะเนการเติมข้อความอัตโนมัติ (เดิม)

บริการ Places เวอร์ชันเดิมช่วยให้คุณเรียกข้อมูลการคาดคะเนการเติมข้อความอัตโนมัติได้โดยใช้โปรแกรม เพื่อให้ควบคุมอินเทอร์เฟซผู้ใช้ได้มากกว่าที่คลาส Autocomplete มีให้ ในตัวอย่างต่อไปนี้ มีการส่งคำขอเดียวสำหรับ "par" โดยมี AutocompletionRequest ซึ่งประกอบด้วย ค่าอินพุตและชุดขอบเขตสำหรับการเอนเอียงการคาดคะเน ตัวอย่าง จะแสดงรายการอินสแตนซ์ AutocompletePrediction และแสดงคำอธิบายของแต่ละอินสแตนซ์ ฟังก์ชันตัวอย่างยัง สร้างโทเค็นเซสชันและใช้กับคำขอด้วย

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);
}

ดึงข้อมูลการทำนายการเติมคำอัตโนมัติ (ใหม่)

นอกจากนี้ คลาส Place ใหม่ยังช่วยให้คุณดึงข้อมูลการทำนายการเติมข้อความอัตโนมัติผ่านโปรแกรมได้ เพื่อควบคุมอินเทอร์เฟซผู้ใช้ได้มากกว่าคลาส PlaceAutocompleteElement ในตัวอย่างต่อไปนี้ มีการร้องขอครั้งเดียวสำหรับ "par" โดยมี AutocompleteRequest ซึ่งประกอบด้วยค่าอินพุตและชุดขอบเขตสำหรับการสร้างอคติในการทำนาย ตัวอย่างนี้จะส่งคืนรายการอินสแตนซ์ placePrediction รายการและแสดงคำอธิบายสำหรับแต่ละรายการ ฟังก์ชันตัวอย่างยังสร้างโทเค็นเซสชันและนำไปใช้กับคำขออีกด้วย

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}`
}

วางวิดเจ็ตการกรอกอัตโนมัติ

ตารางต่อไปนี้แสดงรายการความแตกต่างหลักบางประการในการใช้วิดเจ็ตกรอกข้อความอัตโนมัติระหว่างบริการ Places (รุ่นเก่า) และคลาส Place (ใหม่):

บริการสถานที่ (เดิม) สถานที่ (ใหม่)
Autocomplete ชั้นเรียนสำหรับการทำนายสถานที่ PlaceAutocompleteElement ชั้นเรียนสำหรับการทำนายสถานที่
SearchBox คลาส
สำหรับการทำนายแบบสอบถาม 		การทำนายแบบสอบถามไม่พร้อมใช้งานในคลาส Autocomplete
มีการแปลเฉพาะข้อความตัวแทนอินพุตเริ่มต้นเท่านั้น ตัวแทนการป้อนข้อความ รายการคำทำนาย โลโก้ และการทำนายสถานที่ ล้วนรองรับการระบุตำแหน่งตามภูมิภาค
วิดเจ็ตใช้ setBounds() หรือ autocomplete.bindTo() เพื่อจำกัด (เอนเอียง) การค้นหาให้เป็นขอบเขตที่ระบุ และ strictBounds เพื่อจำกัดผลลัพธ์ให้เป็นขอบเขตที่ระบุ วิดเจ็ตใช้พร็อพเพอร์ตี้ locationBias เพื่อเอนเอียงผลลัพธ์ไปยังขอบเขตที่ระบุ และใช้พร็อพเพอร์ตี้ locationRestriction เพื่อจำกัดการค้นหาให้อยู่ในขอบเขตที่ระบุ
คุณจะผสานรวมวิดเจ็ตได้โดยใช้องค์ประกอบอินพุต HTML มาตรฐานเท่านั้น คุณสามารถผสานรวมวิดเจ็ตได้โดยใช้องค์ประกอบอินพุต HTML มาตรฐานหรือองค์ประกอบ gmp-place-autocomplete
เมื่อใช้วิดเจ็ต ผู้ใช้สามารถขอสิ่งต่างๆ ที่อาจไม่ถูกต้อง (เช่น "bisneyland") ได้ ซึ่งในกรณีนี้จะต้องมีการจัดการอย่างชัดแจ้ง วิดเจ็ตจะแสดงผลลัพธ์สำหรับคำแนะนำที่ระบุเท่านั้น และไม่สามารถส่งคำขอสำหรับค่าใดๆ ได้ ดังนั้นจึงไม่จำเป็นต้องจัดการคำขอที่อาจไม่ถูกต้อง
แสดงอินสแตนซ์ PlaceResult เวอร์ชันเดิม แสดงผลอินสแตนซ์ Place
ฟิลด์ข้อมูลสถานที่ตั้งจะได้รับการตั้งค่าเป็นตัวเลือกสำหรับออบเจ็กต์ Autocomplete ระบบจะตั้งค่าฟิลด์ข้อมูลสถานที่เมื่อผู้ใช้เลือกและเรียกใช้ fetchFields()
จำกัดไว้เฉพาะประเภทสถานที่ และฟิลด์ข้อมูลสถานที่ที่กำหนด สิทธิ์เข้าถึงประเภทสถานที่ และฟิลด์ข้อมูลสถานที่ที่เพิ่มขึ้น

การเปรียบเทียบโค้ด (วิดเจ็ต)

ส่วนนี้จะเปรียบเทียบโค้ดสำหรับการเติมข้อความอัตโนมัติเพื่อแสดงความแตกต่าง ระหว่างวิดเจ็ตการเติมข้อความอัตโนมัติของสถานที่เวอร์ชันเดิมกับองค์ประกอบการเติมข้อความอัตโนมัติของสถานที่เวอร์ชันใหม่

วิดเจ็ต Place Autocomplete (เดิม)

บริการ Places มีวิดเจ็ตการเติมข้อความอัตโนมัติ 2 ประเภท ซึ่งคุณเพิ่มได้โดยใช้คลาส Autocomplete และ SearchBox คุณเพิ่มวิดเจ็ตแต่ละประเภทลงในแผนที่เป็นการควบคุมแผนที่ หรือฝังลงในหน้าเว็บโดยตรงได้ ตัวอย่างโค้ดต่อไปนี้แสดงการฝังวิดเจ็ต Autocomplete เป็นตัวควบคุมแผนที่

  • เครื่องมือสร้างวิดเจ็ต Autocomplete รับอาร์กิวเมนต์ 2 รายการ ดังนี้
    • องค์ประกอบ input ของ HTML ประเภท text นี่คือช่องป้อนข้อมูลที่บริการเติมข้อความอัตโนมัติจะตรวจสอบและแนบผลลัพธ์
    • อาร์กิวเมนต์ AutocompleteOptions ที่ไม่บังคับ ซึ่งคุณสามารถระบุตัวเลือกเพิ่มเติมเพื่อจำกัดการค้นหาได้
  • หากต้องการตั้งค่าขอบเขต คุณสามารถเชื่อมโยงอินสแตนซ์ Autocomplete กับแผนที่อย่างชัดเจนได้โดยการเรียกใช้ autocomplete.bindTo()
  • ระบุช่องข้อมูลสถานที่ในตัวเลือกสำหรับการเติมข้อความอัตโนมัติ
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);
  });
}

วิดเจ็ตการเติมข้อความอัตโนมัติของสถานที่ (ใหม่)

คลาส Place มี PlaceAutocompleteElement ซึ่งเป็นคลาสย่อย HTMLElement ที่มีคอมโพเนนต์ UI ซึ่งเพิ่มลงใน แผนที่เป็นตัวควบคุมแผนที่ หรือฝังลงในหน้าเว็บโดยตรงได้ ตัวอย่างโค้ดต่อไปนี้ แสดงการฝังวิดเจ็ต PlaceAutocompleteElement เป็นตัวควบคุมแผนที่

เราได้ปรับปรุงวิดเจ็ตการเติมข้อความอัตโนมัติของสถานที่ในลักษณะต่อไปนี้

  • UI ของวิดเจ็ตการเติมข้อความอัตโนมัติรองรับการแปลในระดับภูมิภาค (รวมถึงภาษา RTL ) สำหรับตัวยึดตำแหน่งการป้อนข้อความ โลโก้รายการการคาดคะเน และ การคาดคะเนสถานที่
  • การเข้าถึงได้ง่ายขึ้น รวมถึงการรองรับโปรแกรมอ่านหน้าจอและการโต้ตอบด้วยแป้นพิมพ์
  • วิดเจ็ตการเติมข้อความอัตโนมัติจะแสดงผล Place คลาสใหม่เพื่อลดความซับซ้อนในการจัดการ ออบเจ็กต์ที่แสดงผล
  • รองรับอุปกรณ์เคลื่อนที่และหน้าจอขนาดเล็กได้ดียิ่งขึ้น
  • ประสิทธิภาพที่ดีขึ้นและรูปลักษณ์กราฟิกที่ได้รับการปรับปรุง

ความแตกต่างที่สำคัญในการติดตั้งใช้งานมีดังนี้

  • PlaceAutocompleteElement มีช่องป้อนข้อมูลของตัวเอง และจะแทรกลงในหน้าเว็บโดยตรงโดยใช้ HTML หรือ JavaScript (ซึ่งแตกต่างจากการระบุองค์ประกอบอินพุตที่มีอยู่)
  • การคาดการณ์การค้นหาไม่พร้อมใช้งานในคลาส Autocomplete
  • PlaceAutocompleteElement สร้างขึ้นโดยใช้ PlaceAutocompleteElementOptions
    • ระบุฟิลด์ข้อมูลสถานที่เมื่อเลือก (เมื่อเรียกใช้ fetchFields() )
  • ตั้งค่าขอบเขตโดยใช้ตัวเลือก locationBounds หรือ locationRestriction 
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,
  });
}