Places UI Kit: Một thư viện có thể sử dụng ngay, cung cấp không gian tuỳ chỉnh và kiểm soát cho nhà phát triển. Hãy dùng thử và chia sẻ ý kiến của bạn về trải nghiệm dùng Bộ giao diện người dùng.

Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

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)

Place Autocomplete là một tính năng của thư viện Places 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 ứng dụng của mình hành vi tìm kiếm trước 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 Place Autocomplete cũ và mới. Ở 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ó thể lập trình: Dành cho nhà phát triển muốn tuỳ chỉnh và kiểm soát nhiều hơn đối với trải nghiệm tự động hoàn thành.
Tiện ích Place Autocomplete: Một thanh tìm kiếm có thể được nhúng vào bản đồ hoặc trang web.

Giao diện có thể lập trình của tính năng 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 có thể lập 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ụ Place Autocomplete	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 lệnh gọi lại để xử lý đối tượng kết quả và `PlacesServiceStatus` phản hồi.	Sử dụng Lời hứa và hoạt động không đồng bộ.
Các phương thức yêu cầu kiểm tra `PlacesServiceStatus`.	Không cần kiểm tra trạng thái, có thể sử dụng tính năng xử lý lỗi tiêu chuẩn. Tìm hiểu thêm.
Các trường dữ liệu địa điểm được đặt làm tuỳ chọn khi thực thể `Autocomplete` được tạo.	Các trường dữ liệu địa điểm được đặt sau khi `fetchFields()` được gọi.
Các cụm từ gợi ý cho cụm từ tìm kiếm được hỗ trợ (chỉ `SearchBox`).	Các cụm từ gợi ý cho cụm từ tìm kiếm không có trong lớp `Autocomplete`.
Giới hạn ở một tập hợp cố định các loại địa điểm và trường dữ liệu địa điểm.	Truy cập vào một lựa chọn mở rộng các loại địa điểm place types và trường dữ liệu địa điểm.

Các API Tự động hoàn thành cũ và mới đều sử dụng những nội dung sau:

So sánh mã (có thể 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 Dịch vụ Places và lớp Place cho các giao diện có thể lập trình.

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

Dịch vụ Places cũ cho phép bạn truy xuất các cụm từ gợi ý của tính năng 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 để làm sai lệch cụm từ gợi ý. Ví dụ này trả về danh sách các AutocompletePrediction thực thể, và cho thấy nội dung mô tả cho từng thực thể. Hàm ví dụ cũng tạo mã phiên và áp dụng mã đó 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 Place mới cũng cho phép bạn truy xuất các cụm từ gợi ý của tính năng 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 để làm sai lệch cụm từ gợi ý. Ví dụ này trả về 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ụ cũng tạo mã phiên và áp dụng mã đó 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}`
}

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

Dịch vụ Places (Cũ)	Địa điểm (Mới)
`Autocomplete` lớp cho các cụm từ gợi ý về địa điểm.	`PlaceAutocompleteElement` lớp cho các cụm từ gợi ý về địa điểm.
`SearchBox` lớp cho các cụm từ gợi ý về cụm từ tìm kiếm.	Các cụm từ gợi ý cho cụm từ tìm kiếm không có trong lớp `Autocomplete`.
Chỉ văn bản giữ chỗ đầu vào mặc định được bản địa hoá.	Văn bản giữ chỗ đầu vào, biểu trưng danh sách cụm từ gợi ý và cụm từ gợi ý về đị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()` để giới hạn (làm sai lệch) cụm từ tìm kiếm theo ranh giới đã chỉ định và `strictBounds` để giới hạn kết quả theo ranh giới đã chỉ định.	Tiện ích sử dụng thuộc tính `locationBias` để làm sai lệch kết quả theo ranh giới đã chỉ định và thuộc tính `locationRestriction` để giới hạn cụm từ tìm kiếm theo ranh giới đã chỉ định.
Bạn chỉ 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.	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, người dùng có thể yêu cầu những nội dung không hợp lệ (ví dụ: "bisneyland"); bạn phải xử lý rõ ràng trường hợp này.	Tiện ích sẽ chỉ trả về kết quả cho các cụm từ gợi ý đượ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ề thực thể cũ `PlaceResult`.	Trả về thực thể `Place`.
Các trường dữ liệu địa điểm được đặt làm tuỳ chọn cho đối tượng `Autocomplete`.	Các trường dữ liệu địa điểm được đặt khi người dùng chọn và `fetchFields()` được gọi.
Giới hạn ở một tập hợp cố định các loại địa điểm và trường dữ liệu địa điểm.	Truy cập vào một lựa chọn mở rộng các loại địa điểm place types 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 Place Autocomplete cũ và phần tử Place Autocomplete mới.

Tiện ích Place Autocomplete (cũ)

Dịch vụ Places 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 một chế độ điều khiển 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 tiện ích Autocomplete dưới dạng một chế độ điều khiển bản đồ.

Hàm khởi tạo tiện ích Autocomplete nhận 2 đối số:
- Phần tử HTML input thuộc loại text. Đây là trường nhập dữ liệu mà dịch vụ tự động hoàn thành sẽ theo dõi và đính kèm kết quả.
- Đối số AutocompleteOptions không bắt buộc, trong đó bạn có thể chỉ định thêm các tuỳ chọn để giới hạn cụm từ tìm kiếm.
Để đặ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 địa điểm trong các tuỳ chọn cho tính năng 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 một chế độ điều khiển 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 tiện ích PlaceAutocompleteElement dưới dạng một chế độ điều khiển bản đồ.

Tiện ích Place Autocomplete đã đượ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ả ngôn ngữ RTL) cho văn bản giữ chỗ đầu vào, biểu trưng danh sách cụm từ gợi ý và cụm từ gợi ý 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ợ cho trình đọc màn hình và tương tác bằng bàn phím.
Tiện ích Tự động hoàn thành 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ỏ.
Cải thiện hiệu suất và giao diện đồ hoạ.

Một số điểm khác biệt chính trong quá trình triển khai:

PlaceAutocompleteElement cung cấp trường nhập dữ 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ử đầu vào hiện có).
Các cụm từ gợi ý cho cụm từ tìm kiếm không có trong lớp Autocomplete.
PlaceAutocompleteElement được tạo bằng PlaceAutocompleteElementOptions.
- Các trường dữ liệu địa điểm được chỉ định tại thời điểm chọn (khi fetchFields() được gọi).
Đặt ranh giới bằng cách sử dụng tuỳ 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 ( 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,
  });
}