Di chuyển sang tính năng Tự động hoàn tất địa điểm mới

Nhà phát triển ở Khu vực kinh tế Châu Âu (EEA)

Tính năng Tự động hoàn thành địa điểm là một tính năng của Thư viện địa điểm trong Maps JavaScript API. Bạn có thể sử dụng tính năng tự động hoàn thành để cung cấp cho các ứng dụng của mình hành vi tìm kiếm dự đoán của trường tìm kiếm trên Google Maps.

Trang này giải thích sự khác biệt giữa các tính năng Cũ và Mới của tính năng Tự động hoàn thành địa điểm. Trong cả hai phiên bản, có 2 cách chung để tích hợp tính năng Tự động hoàn thành:

Giao diện có lập trình để tự động hoàn thành

Bảng sau đây liệt kê một số điểm khác biệt chính trong việc sử dụng tính năng Place Autocomplete theo chương trình giữa Dịch vụ Place Autocomplete (cũ) và Autocomplete Data API (mới):

PlacesService (Cũ) Place (Mới)
Tài liệu tham khảo về Dịch vụ tự động hoàn thành địa điểm Tài liệu tham khảo về Dữ liệu tự động hoàn thành (mới)
AutocompletionRequest AutocompleteRequest
AutocompleteService.getPlacePredictions AutocompleteSuggestion.fetchAutocompleteSuggestions
AutocompletePrediction PlacePrediction
Các phương thức yêu cầu sử dụng một lệnh gọi lại để xử lý đối tượng kết quả và phản hồi PlacesServiceStatus. Sử dụng Promise và hoạt động không đồng bộ.
Các phương thức yêu cầu phải có chế độ kiểm tra PlacesServiceStatus. Không cần kiểm tra trạng thái bắt buộc, có thể sử dụng quy trình xử lý lỗi tiêu chuẩn. Tìm hiểu thêm.
Các trường dữ liệu vị trí được đặt làm lựa chọn khi phiên bản Autocomplete được tạo. Các trường dữ liệu về địa điểm sẽ được đặt sau khi fetchFields() được gọi.
Tính năng dự đoán cụm từ tìm kiếm được hỗ trợ (chỉ SearchBox). Không có tính năng dự đoán cụm từ tìm kiếm trong lớp Autocomplete.
Chỉ giới hạn ở một nhóm cố định gồm các loại địa điểm và các trường dữ liệu địa điểm. Quyền truy cập vào nhiều loại địa điểm và trường dữ liệu địa điểm.

Cả Autocomplete API cũ và mới đều sử dụng những thông tin sau:

So sánh mã (có lập trình)

Phần này so sánh mã cho tính năng tự động hoàn thành để minh hoạ sự khác biệt giữa Places Service và lớp Place, đối với các giao diện có thể lập trình.

Truy xuất cụm từ gợi ý của tính năng tự động hoàn thành (phiên bản cũ)

Places Service cũ cho phép bạn truy xuất các đề xuất tự động hoàn thành theo phương thức lập trình, để kiểm soát giao diện người dùng nhiều hơn so với lớp Autocomplete. Trong ví dụ sau, một yêu cầu duy nhất được thực hiện cho "par", với AutocompletionRequest bao gồm giá trị đầu vào và một tập hợp các ranh giới để điều chỉnh dự đoán. Ví dụ này trả về một danh sách các thực thể AutocompletePrediction và cho thấy nội dung mô tả cho từng thực thể. Hàm ví dụ này cũng tạo một mã thông báo phiên và áp dụng mã thông báo đó cho yêu cầu.

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

Truy xuất các cụm từ gợi ý của tính năng tự động hoàn thành (mới)

Lớp Địa điểm mới cũng cho phép bạn truy xuất các đề xuất tự động hoàn thành theo phương thức lập trình để kiểm soát giao diện người dùng nhiều hơn so với lớp PlaceAutocompleteElement. Trong ví dụ sau, một yêu cầu duy nhất được thực hiện cho "par", với AutocompleteRequest bao gồm giá trị đầu vào và một tập hợp các ranh giới để điều chỉnh dự đoán. Ví dụ này trả về một danh sách các thực thể placePrediction và cho thấy nội dung mô tả cho từng thực thể. Hàm ví dụ này cũng tạo một mã thông báo phiên và áp dụng mã thông báo đó cho yêu cầu.

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

Tiện ích Place Autocomplete

Bảng sau đây liệt kê một số điểm khác biệt chính trong việc sử dụng các tiện ích tự động hoàn thành giữa dịch vụ Places (cũ) và lớp Place (mới):

Places Service (Cũ) Địa điểm (Mới)
Lớp Autocomplete để dự đoán địa điểm. Lớp PlaceAutocompleteElement để dự đoán địa điểm.
Lớp SearchBox
để dự đoán truy vấn. 		Không có tính năng dự đoán cụm từ tìm kiếm trong lớp Autocomplete.
Chỉ có văn bản giữ chỗ mặc định của dữ liệu đầu vào được bản địa hoá. Phần giữ chỗ nhập văn bản, biểu trưng danh sách dự đoán và dự đoán địa điểm đều hỗ trợ bản địa hoá theo khu vực.
Tiện ích sử dụng setBounds() hoặc autocomplete.bindTo() để hạn chế (thiên vị) phạm vi tìm kiếm trong các ranh giới đã chỉ định và strictBounds để hạn chế kết quả trong các ranh giới đã chỉ định. Tiện ích này sử dụng thuộc tính locationBias để điều chỉnh kết quả theo ranh giới đã chỉ định và thuộc tính locationRestriction để hạn chế tìm kiếm trong ranh giới đã chỉ định.
Bạn chỉ có thể tích hợp các tiện ích bằng cách sử dụng một phần tử đầu vào HTML tiêu chuẩn. Bạn có thể tích hợp tiện ích bằng cách sử dụng phần tử đầu vào HTML tiêu chuẩn hoặc phần tử gmp-place-autocomplete.
Khi sử dụng tiện ích này, người dùng có thể yêu cầu những thứ không hợp lệ (ví dụ: "bisneyland"); trường hợp này phải được xử lý rõ ràng. Tiện ích này sẽ chỉ trả về kết quả cho các đề xuất được cung cấp và không thể đưa ra yêu cầu cho các giá trị tuỳ ý; do đó, bạn không cần xử lý các yêu cầu có thể không hợp lệ.
Trả về phiên bản PlaceResult cũ. Trả về thực thể Place.
Các trường dữ liệu địa điểm được đặt làm lựa chọn cho đối tượng Autocomplete. Các trường dữ liệu về địa điểm được đặt khi người dùng chọn và fetchFields() được gọi.
Chỉ giới hạn ở một nhóm cố định gồm các loại địa điểm và các trường dữ liệu địa điểm. Quyền truy cập vào nhiều loại địa điểm và trường dữ liệu địa điểm.

So sánh mã (tiện ích)

Phần này so sánh mã cho tính năng tự động hoàn thành để minh hoạ sự khác biệt giữa Tiện ích tự động hoàn thành địa điểm cũ và phần tử Tự động hoàn thành địa điểm mới.

Tiện ích Place Autocomplete (cũ)

Places Service cung cấp 2 loại tiện ích tự động hoàn thành mà bạn có thể thêm bằng cách sử dụng các lớp Autocomplete và SearchBox. Bạn có thể thêm từng loại tiện ích vào bản đồ dưới dạng chế độ kiểm soát bản đồ hoặc nhúng trực tiếp vào trang web. Ví dụ về mã sau đây cho thấy cách nhúng một tiện ích Autocomplete làm chế độ điều khiển bản đồ.

  • Hàm khởi tạo tiện ích Autocomplete nhận hai đối số:
    • Một phần tử input HTML thuộc loại text. Đây là trường nhập liệu mà dịch vụ tự động hoàn thành sẽ theo dõi và đính kèm kết quả vào.
    • Đối số AutocompleteOptions không bắt buộc, trong đó bạn có thể chỉ định thêm các lựa chọn để hạn chế truy vấn.
  • Để đặt ranh giới, bạn có thể liên kết rõ ràng thực thể Autocomplete với bản đồ bằng cách gọi autocomplete.bindTo().
  • Chỉ định các trường dữ liệu về địa điểm trong các lựa chọn để tự động hoàn thành.
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);
  });
}

Tiện ích Place Autocomplete (Mới)

Lớp Place cung cấp PlaceAutocompleteElement, một lớp con HTMLElement cung cấp thành phần giao diện người dùng có thể được thêm vào bản đồ dưới dạng chế độ kiểm soát bản đồ hoặc được nhúng trực tiếp vào một trang web. Ví dụ về mã sau đây cho thấy cách nhúng một tiện ích PlaceAutocompleteElement dưới dạng chế độ điều khiển bản đồ.

Tiện ích Tự động hoàn thành địa điểm đã được cải thiện theo những cách sau:

  • Giao diện người dùng của tiện ích Tự động hoàn thành hỗ trợ bản địa hoá theo khu vực (bao gồm cả các ngôn ngữ viết từ phải sang trái), cho phần giữ chỗ nhập văn bản, biểu trưng danh sách dự đoán và các dự đoán về địa điểm.
  • Cải thiện khả năng hỗ trợ tiếp cận, bao gồm cả tính năng hỗ trợ trình đọc màn hình và tương tác bằng bàn phím.
  • Tiện ích Autocomplete trả về lớp Place mới để đơn giản hoá việc xử lý đối tượng được trả về.
  • Hỗ trợ tốt hơn cho thiết bị di động và màn hình nhỏ.
  • Hiệu suất tốt hơn và giao diện đồ hoạ cải thiện.

Sau đây là những điểm khác biệt chính trong quá trình triển khai:

  • PlaceAutocompleteElement cung cấp trường nhập liệu riêng và được chèn trực tiếp vào trang bằng HTML hoặc JavaScript (thay vì được cung cấp một phần tử nhập liệu hiện có).
  • Không có tính năng dự đoán cụm từ tìm kiếm trong lớp Autocomplete.
  • PlaceAutocompleteElement được tạo bằng PlaceAutocompleteElementOptions.
    • Các trường dữ liệu về địa điểm được chỉ định tại thời điểm lựa chọn (khi fetchFields() được gọi).
  • Đặt ranh giới bằng cách sử dụng lựa chọn locationBounds hoặc 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,
  });
}