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

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

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

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

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

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

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

ทั้ง Autocomplete API แบบเดิมและแบบใหม่ใช้รายการต่อไปนี้

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

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

ดึงข้อมูลการคาดคะเนการเติมข้อความอัตโนมัติ (แบบเดิม)

Places Service แบบเดิมช่วยให้คุณดึงข้อมูลการคาดคะเนการเติมข้อความอัตโนมัติแบบเป็นโปรแกรมได้ เพื่อให้ควบคุมอินเทอร์เฟซผู้ใช้ได้มากขึ้นกว่าที่คลาส 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}`
}

วิดเจ็ต Place Autocomplete

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

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

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

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

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

Places Service มีวิดเจ็ตการเติมข้อความอัตโนมัติ 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 เป็นการควบคุมแผนที่

วิดเจ็ต Place Autocomplete ได้รับการปรับปรุงในด้านต่อไปนี้

  • UI ของวิดเจ็ตการเติมข้อความอัตโนมัติรองรับการแปลเป็นภาษาท้องถิ่น (รวมถึงภาษาที่เขียนจากขวาไปซ้าย) สำหรับตัวยึดตำแหน่งอินพุตข้อความ โลโก้รายการการคาดคะเน และการคาดคะเนสถานที่
  • การเข้าถึงที่ได้รับการปรับปรุง รวมถึงการรองรับโปรแกรมอ่านหน้าจอและการโต้ตอบด้วยแป้นพิมพ์
  • วิดเจ็ตการเติมข้อความอัตโนมัติแสดงผลคลาส 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 ( event ) => {
    const place = event.placePrediction.toPlace();
    await place.fetchFields({
      fields: ["displayName", "formattedAddress", "location", "viewport"],
    });
    // 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,
  });
}