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

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

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

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

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

ตารางต่อไปนี้แสดงความแตกต่างหลักบางประการในการใช้ Place Autocomplete แบบเป็นโปรแกรมระหว่างบริการ Place Autocomplete (เดิม) กับ 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()
จำกัดไว้เฉพาะประเภทสถานที่ และฟิลด์ข้อมูลสถานที่ที่กำหนด สิทธิ์เข้าถึงประเภทสถานที่ และฟิลด์ข้อมูลสถานที่ที่เพิ่มขึ้น

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

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

วิดเจ็ต 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 Autocomplete (ใหม่)

คลาส 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,
  });
}