ย้ายข้อมูลไปยัง 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
เมธอดกำหนดให้ใช้ Callback เพื่อจัดการออบเจ็กต์ผลลัพธ์และ 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"],
    });
    // 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,
  });
}