Tự động hoàn thành địa điểm

Giới thiệu

Tính năng tự động hoàn thành 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. Dịch vụ tự động hoàn thành có thể so khớp với các từ và chuỗi con đầy đủ, phân giải tên địa điểm, địa chỉ và plus code. Do đó, các ứng dụng có thể gửi truy vấn khi người dùng nhập để cung cấp thông tin dự đoán về địa điểm ngay lập tức. Theo định nghĩa của Places API, "địa điểm" có thể là một cơ sở, vị trí địa lý hoặc một địa điểm yêu thích nổi bật.

Bắt đầu

Trước khi sử dụng thư viện Places trong Maps JavaScript API, trước tiên hãy xác minh rằng Places API đã được bật trong Google Cloud Console, trong cùng một dự án mà bạn thiết lập cho Maps JavaScript API.

Cách xem danh sách các API đã bật:

1. Chuyển đến Bảng điều khiển Google Cloud.
2. Nhấp vào nút Chọn một dự án, sau đó chọn cùng một dự án mà bạn đã thiết lập cho Maps JavaScript API rồi nhấp vào Mở.
3. Trong danh sách API trên Trang tổng quan, hãy tìm Places API.
4. Nếu thấy API đó trong danh sách, thì bạn không cần làm gì thêm. Tuy nhiên, dự án này đang ở trạng thái Legacy. Để biết thêm thông tin về giai đoạn Cũ và cách di chuyển từ các dịch vụ Cũ sang các dịch vụ mới hơn, hãy xem bài viết Các sản phẩm và tính năng cũ. Có một trường hợp ngoại lệ đối với các tiện ích Tự động hoàn thành và SearchBox. Đây chưa phải là sản phẩm GA trên Places API (Mới).

Tải thư viện

Dịch vụ Địa điểm là một thư viện độc lập, tách biệt với mã API JavaScript chính của Maps. Để sử dụng các tính năng có trong thư viện này, trước tiên, bạn phải tải thư viện này bằng cách sử dụng tham số libraries trong URL khởi động Maps API:

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&libraries=places&callback=initMap">
</script>

Hãy xem bài viết Tổng quan về thư viện để biết thêm thông tin.

Tóm tắt các lớp học

API này 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 tương ứng. Ngoài ra, bạn có thể dùng lớp AutocompleteService để truy xuất kết quả tự động hoàn thành theo phương thức lập trình (xem Tài liệu tham khảo về API JavaScript của Maps: lớp AutocompleteService).

Dưới đây là bản tóm tắt về các lớp có sẵn:

• Autocomplete sẽ thêm một trường nhập văn bản vào trang web của bạn và theo dõi trường đó để biết các mục nhập ký tự. Khi người dùng nhập văn bản, tính năng tự động hoàn thành sẽ trả về các dự đoán về địa điểm dưới dạng danh sách thả xuống. Khi người dùng chọn một địa điểm trong danh sách, thông tin về địa điểm đó sẽ được trả về đối tượng tự động hoàn thành và ứng dụng của bạn có thể truy xuất thông tin này. Xem thông tin chi tiết bên dưới.

  

  

• SearchBox sẽ thêm một trường nhập văn bản vào trang web của bạn, tương tự như Autocomplete. Sau đây là những điểm khác biệt:
  • Điểm khác biệt chính nằm ở kết quả xuất hiện trong danh sách chọn. SearchBox cung cấp danh sách mở rộng các cụm từ gợi ý, có thể bao gồm các địa điểm (theo định nghĩa của Places API) cùng với các cụm từ tìm kiếm được đề xuất. Ví dụ: nếu người dùng nhập "pizza ở new", danh sách lựa chọn có thể bao gồm cụm từ "pizza ở New York, NY" cũng như tên của nhiều cửa hàng pizza.
  • SearchBox cung cấp ít lựa chọn hơn Autocomplete để hạn chế phạm vi tìm kiếm. Trong trường hợp trước, bạn có thể thiên về một LatLngBounds nhất định. Trong phần sau, bạn có thể hạn chế tìm kiếm ở một quốc gia cụ thể và các loại địa điểm cụ thể, cũng như đặt ranh giới. Để biết thêm thông tin, hãy xem bên dưới.

  

  Xem thông tin chi tiết bên dưới.
• Bạn có thể tạo một đối tượng AutocompleteService để truy xuất thông tin dự đoán theo phương thức lập trình. Gọi getPlacePredictions() để truy xuất các địa điểm phù hợp hoặc gọi getQueryPredictions() để truy xuất các địa điểm phù hợp cùng với các cụm từ tìm kiếm được đề xuất. Lưu ý: AutocompleteService không thêm bất kỳ chế độ kiểm soát nào trên giao diện người dùng. Thay vào đó, các phương thức trên sẽ trả về một mảng các đối tượng dự đoán. Mỗi đối tượng dự đoán chứa văn bản của dự đoán, cũng như thông tin tham chiếu và thông tin chi tiết về cách kết quả khớp với dữ liệu đầu vào của người dùng. Xem thông tin chi tiết bên dưới.

Thêm tiện ích Tự động hoàn thành

Tiện ích Autocomplete tạo một trường nhập văn bản trên trang web của bạn, cung cấp thông tin dự đoán về các địa điểm trong danh sách chọn trên giao diện người dùng và trả về thông tin chi tiết về địa điểm để phản hồi yêu cầu getPlace(). Mỗi mục trong danh sách chọn tương ứng với một địa điểm duy nhất (do Places API xác định).

Hàm khởi tạo 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ả.
• Đối số AutocompleteOptions (không bắt buộc) có thể chứa các thuộc tính sau:
  • Một mảng dữ liệu fields sẽ được đưa vào phản hồi Place Details cho PlaceResult mà người dùng đã chọn. Nếu bạn không đặt thuộc tính hoặc nếu ['ALL'] được truyền vào, thì tất cả các trường có sẵn sẽ được trả về và tính phí (không nên dùng cách này cho các hoạt động triển khai sản xuất). Để xem danh sách các trường, hãy xem PlaceResult.
  • Một mảng types chỉ định một loại rõ ràng hoặc một tập hợp loại, như được liệt kê trong các loại được hỗ trợ. Nếu bạn không chỉ định loại nào, thì tất cả các loại sẽ được trả về.
  • bounds là một đối tượng google.maps.LatLngBounds chỉ định khu vực để tìm kiếm địa điểm. Kết quả sẽ thiên về, nhưng không giới hạn ở những địa điểm nằm trong phạm vi này.
  • strictBounds là một boolean chỉ định xem API chỉ được trả về những địa điểm nằm hoàn toàn trong khu vực do bounds đã cho xác định hay không. API không trả về kết quả bên ngoài khu vực này ngay cả khi kết quả đó khớp với thông tin đầu vào của người dùng.
  • Bạn có thể dùng componentRestrictions để giới hạn kết quả trong các nhóm cụ thể. Bạn có thể sử dụng componentRestrictions để lọc theo tối đa 5 quốc gia. Bạn phải truyền quốc gia dưới dạng mã quốc gia gồm 2 ký tự, tương thích với ISO 3166-1 Alpha-2. Bạn phải chuyển nhiều quốc gia dưới dạng danh sách mã quốc gia.

    Lưu ý: Nếu bạn nhận được kết quả không mong muốn với một mã quốc gia, hãy xác minh rằng bạn đang sử dụng mã bao gồm các quốc gia, lãnh thổ phụ thuộc và khu vực đặc biệt mà bạn muốn. Bạn có thể tìm thông tin về mã tại Wikipedia: Danh sách mã quốc gia theo ISO 3166 hoặc Nền tảng duyệt web trực tuyến của ISO.

  • Bạn có thể dùng placeIdOnly để hướng dẫn tiện ích Autocomplete chỉ truy xuất mã địa điểm. Khi gọi getPlace() trên đối tượng Autocomplete, PlaceResult được cung cấp sẽ chỉ có các thuộc tính place id, types và name được đặt. Bạn có thể sử dụng mã địa điểm được trả về với các lệnh gọi đến dịch vụ Địa điểm, Dịch vụ mã hoá địa lý, Dịch vụ chỉ đường hoặc Dịch vụ ma trận khoảng cách.

Hạn chế cụm từ gợi ý của tính năng Tự động hoàn thành

Theo mặc định, tính năng Tự động hoàn thành địa điểm sẽ trình bày tất cả các loại địa điểm, thiên về những dự đoán gần vị trí của người dùng và tìm nạp tất cả các trường dữ liệu có sẵn cho địa điểm mà người dùng đã chọn. Đặt các lựa chọn Tự động hoàn thành tên địa điểm để đưa ra những dự đoán phù hợp hơn dựa trên trường hợp sử dụng của bạn.

Đặt các lựa chọn tại thời điểm tạo

Hàm khởi tạo Autocomplete chấp nhận một tham số AutocompleteOptions để đặt các quy tắc ràng buộc khi tạo tiện ích. Ví dụ sau đây đặt các lựa chọn bounds, componentRestrictions và types để yêu cầu các địa điểm thuộc loại establishment, ưu tiên những địa điểm trong khu vực địa lý được chỉ định và chỉ giới hạn các đề xuất cho những địa điểm ở Hoa Kỳ. Việc đặt lựa chọn fields sẽ chỉ định thông tin cần trả về về địa điểm mà người dùng đã chọn.

Gọi setOptions() để thay đổi giá trị của một lựa chọn cho tiện ích hiện có.

const center = { lat: 50.064192, lng: -130.605469 };
// Create a bounding box with sides ~10km away from the center point
const defaultBounds = {
  north: center.lat + 0.1,
  south: center.lat - 0.1,
  east: center.lng + 0.1,
  west: center.lng - 0.1,
};
const input = document.getElementById("pac-input") as HTMLInputElement;
const options = {
  bounds: defaultBounds,
  componentRestrictions: { country: "us" },
  fields: ["address_components", "geometry", "icon", "name"],
  strictBounds: false,
};

const autocomplete = new google.maps.places.Autocomplete(input, options);
index.ts

const center = { lat: 50.064192, lng: -130.605469 };
// Create a bounding box with sides ~10km away from the center point
const defaultBounds = {
  north: center.lat + 0.1,
  south: center.lat - 0.1,
  east: center.lng + 0.1,
  west: center.lng - 0.1,
};
const input = document.getElementById("pac-input");
const options = {
  bounds: defaultBounds,
  componentRestrictions: { country: "us" },
  fields: ["address_components", "geometry", "icon", "name"],
  strictBounds: false,
};
const autocomplete = new google.maps.places.Autocomplete(input, options);
index.js

Chỉ định các trường dữ liệu

Chỉ định các trường dữ liệu để tránh bị tính phí cho SKU Dữ liệu về địa điểm mà bạn không cần. Đưa thuộc tính fields vào AutocompleteOptions được truyền đến hàm khởi tạo tiện ích, như minh hoạ trong ví dụ trước, hoặc gọi setFields() trên một đối tượng Autocomplete hiện có.

autocomplete.setFields(["place_id", "geometry", "name"]);

Xác định các thiên kiến và ranh giới khu vực tìm kiếm cho tính năng Tự động hoàn thành

Bạn có thể điều chỉnh kết quả tự động hoàn thành để ưu tiên một vị trí hoặc khu vực gần đúng theo những cách sau:

• Đặt ranh giới khi tạo đối tượng Autocomplete.
• Thay đổi ranh giới trên một Autocomplete hiện có.
• Đặt ranh giới cho khung nhìn của bản đồ.
• Hạn chế tìm kiếm trong phạm vi.
• Hạn chế phạm vi tìm kiếm ở một quốc gia cụ thể.

Ví dụ trước minh hoạ cách đặt ranh giới khi tạo. Các ví dụ sau đây minh hoạ các kỹ thuật thiên vị khác.

Thay đổi ranh giới của tính năng Tự động hoàn thành hiện có

Gọi setBounds() để thay đổi vùng tìm kiếm trên Autocomplete hiện có thành các ranh giới hình chữ nhật.

const southwest = { lat: 5.6108, lng: 136.589326 };
const northeast = { lat: 61.179287, lng: 2.64325 };
const newBounds = new google.maps.LatLngBounds(southwest, northeast);

autocomplete.setBounds(newBounds);
index.ts

const southwest = { lat: 5.6108, lng: 136.589326 };
const northeast = { lat: 61.179287, lng: 2.64325 };
const newBounds = new google.maps.LatLngBounds(southwest, northeast);

autocomplete.setBounds(newBounds);
index.js

Đặt ranh giới cho khung nhìn của bản đồ

Sử dụng bindTo() để điều chỉnh kết quả theo khung hiển thị của bản đồ, ngay cả khi khung hiển thị đó thay đổi.

autocomplete.bindTo("bounds", map);
index.ts

autocomplete.bindTo("bounds", map);
index.js

Sử dụng unbind() để huỷ liên kết các cụm từ gợi ý của tính năng Tự động hoàn thành với khung hiển thị của bản đồ.

autocomplete.unbind("bounds");
autocomplete.setBounds({ east: 180, west: -180, north: 90, south: -90 });
index.ts

autocomplete.unbind("bounds");
autocomplete.setBounds({ east: 180, west: -180, north: 90, south: -90 });
index.js

Xem ví dụ

Hạn chế tìm kiếm trong phạm vi hiện tại

Đặt lựa chọn strictBounds để giới hạn kết quả trong phạm vi hiện tại, cho dù dựa trên khung nhìn bản đồ hay phạm vi hình chữ nhật.

autocomplete.setOptions({ strictBounds: true });

Giới hạn gợi ý cho một quốc gia cụ thể

Sử dụng lựa chọn componentRestrictions hoặc gọi setComponentRestrictions() để giới hạn tìm kiếm bằng tính năng tự động hoàn thành trong một nhóm cụ thể gồm tối đa 5 quốc gia.

autocomplete.setComponentRestrictions({
  country: ["us", "pr", "vi", "gu", "mp"],
});
index.ts

autocomplete.setComponentRestrictions({
  country: ["us", "pr", "vi", "gu", "mp"],
});
index.js

Xem ví dụ

Hạn chế các loại địa điểm

Sử dụng lựa chọn types hoặc gọi setTypes() để giới hạn các dự đoán đối với một số loại địa điểm nhất định. Ràng buộc này chỉ định một loại hoặc một tập hợp loại, như được liệt kê trong Các loại địa điểm. Nếu bạn không chỉ định quy tắc ràng buộc nào, thì tất cả các loại sẽ được trả về.

Đối với giá trị của lựa chọn types hoặc giá trị được truyền đến setTypes(), bạn có thể chỉ định một trong hai giá trị sau:

• Một mảng chứa tối đa 5 giá trị từ Bảng 1 hoặc Bảng 2 trong Các loại địa điểm. Ví dụ:

  types: ['hospital', 'pharmacy', 'bakery', 'country']

  hoặc:

  autocomplete.setTypes(['hospital', 'pharmacy', 'bakery', 'country']);

• Một bộ lọc bất kỳ trong Bảng 3 từ Loại địa điểm. Bạn chỉ có thể chỉ định một giá trị duy nhất trong Bảng 3.

Yêu cầu sẽ bị từ chối nếu:

• Bạn chỉ định nhiều hơn 5 loại.
• Bạn chỉ định mọi loại không nhận dạng được.
• Bạn có thể kết hợp mọi loại từ Bảng 1 hoặc Bảng 2 với mọi bộ lọc từ Bảng 3.

Bản minh hoạ tính năng Tự động hoàn thành địa điểm minh hoạ sự khác biệt về các cụm từ dự đoán giữa các loại địa điểm.

Xem bản minh hoạ

Lấy thông tin về địa điểm

Khi người dùng chọn một địa điểm trong số các kết quả dự đoán được đính kèm vào trường văn bản tự động hoàn thành, dịch vụ sẽ kích hoạt một sự kiện place_changed. Cách nhận thông tin chi tiết về địa điểm:

1. Tạo một trình xử lý sự kiện cho sự kiện place_changed và gọi addListener() trên đối tượng Autocomplete để thêm trình xử lý.
2. Gọi Autocomplete.getPlace() trên đối tượng Autocomplete để truy xuất đối tượng PlaceResult. Sau đó, bạn có thể dùng đối tượng này để biết thêm thông tin về địa điểm đã chọn.

Theo mặc định, khi người dùng chọn một địa điểm, tính năng tự động hoàn thành sẽ trả về tất cả các trường dữ liệu có sẵn cho địa điểm đã chọn và bạn sẽ được tính phí tương ứng. Sử dụng Autocomplete.setFields() để chỉ định những trường dữ liệu địa điểm cần trả về. Đọc thêm về đối tượng PlaceResult, bao gồm danh sách các trường dữ liệu về địa điểm mà bạn có thể yêu cầu. Để tránh trả tiền cho dữ liệu không cần thiết, hãy nhớ sử dụng Autocomplete.setFields() để chỉ định dữ liệu địa điểm mà bạn sẽ sử dụng.

Thuộc tính name chứa description từ các cụm từ gợi ý của tính năng Tự động hoàn thành địa điểm. Bạn có thể đọc thêm về description trong tài liệu về tính năng Tự động hoàn thành địa điểm.

Đối với biểu mẫu địa chỉ, bạn nên lấy địa chỉ ở định dạng có cấu trúc. Để trả về địa chỉ có cấu trúc cho địa điểm đã chọn, hãy gọi Autocomplete.setFields() và chỉ định trường address_components.

Ví dụ sau đây sử dụng tính năng tự động hoàn thành để điền các trường trong biểu mẫu địa chỉ.

function fillInAddress() {
  // Get the place details from the autocomplete object.
  const place = autocomplete.getPlace();
  let address1 = "";
  let postcode = "";

  // Get each component of the address from the place details,
  // and then fill-in the corresponding field on the form.
  // place.address_components are google.maps.GeocoderAddressComponent objects
  // which are documented at http://goo.gle/3l5i5Mr
  for (const component of place.address_components as google.maps.GeocoderAddressComponent[]) {
    // @ts-ignore remove once typings fixed
    const componentType = component.types[0];

    switch (componentType) {
      case "street_number": {
        address1 = `${component.long_name} ${address1}`;
        break;
      }

      case "route": {
        address1 += component.short_name;
        break;
      }

      case "postal_code": {
        postcode = `${component.long_name}${postcode}`;
        break;
      }

      case "postal_code_suffix": {
        postcode = `${postcode}-${component.long_name}`;
        break;
      }

      case "locality":
        (document.querySelector("#locality") as HTMLInputElement).value =
          component.long_name;
        break;

      case "administrative_area_level_1": {
        (document.querySelector("#state") as HTMLInputElement).value =
          component.short_name;
        break;
      }

      case "country":
        (document.querySelector("#country") as HTMLInputElement).value =
          component.long_name;
        break;
    }
  }

  address1Field.value = address1;
  postalField.value = postcode;

  // After filling the form with address components from the Autocomplete
  // prediction, set cursor focus on the second address line to encourage
  // entry of subpremise information such as apartment, unit, or floor number.
  address2Field.focus();
}
index.ts

function fillInAddress() {
  // Get the place details from the autocomplete object.
  const place = autocomplete.getPlace();
  let address1 = "";
  let postcode = "";

  // Get each component of the address from the place details,
  // and then fill-in the corresponding field on the form.
  // place.address_components are google.maps.GeocoderAddressComponent objects
  // which are documented at http://goo.gle/3l5i5Mr
  for (const component of place.address_components) {
    // @ts-ignore remove once typings fixed
    const componentType = component.types[0];

    switch (componentType) {
      case "street_number": {
        address1 = `${component.long_name} ${address1}`;
        break;
      }

      case "route": {
        address1 += component.short_name;
        break;
      }

      case "postal_code": {
        postcode = `${component.long_name}${postcode}`;
        break;
      }

      case "postal_code_suffix": {
        postcode = `${postcode}-${component.long_name}`;
        break;
      }
      case "locality":
        document.querySelector("#locality").value = component.long_name;
        break;
      case "administrative_area_level_1": {
        document.querySelector("#state").value = component.short_name;
        break;
      }
      case "country":
        document.querySelector("#country").value = component.long_name;
        break;
    }
  }

  address1Field.value = address1;
  postalField.value = postcode;
  // After filling the form with address components from the Autocomplete
  // prediction, set cursor focus on the second address line to encourage
  // entry of subpremise information such as apartment, unit, or floor number.
  address2Field.focus();
}

window.initAutocomplete = initAutocomplete;
index.js

Xem ví dụ

Tuỳ chỉnh văn bản phần giữ chỗ

Theo mặc định, trường văn bản do dịch vụ tự động hoàn thành tạo ra sẽ chứa văn bản giữ chỗ tiêu chuẩn. Để sửa đổi văn bản, hãy đặt thuộc tính placeholder trên phần tử input:

<input id="searchTextField" type="text" size="50" placeholder="Anything you want!">

Lưu ý: Văn bản giữ chỗ mặc định sẽ được bản địa hoá tự động. Nếu chỉ định giá trị phần giữ chỗ của riêng mình, bạn phải xử lý việc bản địa hoá giá trị đó trong ứng dụng. Để biết thông tin về cách API JavaScript của Google Maps chọn ngôn ngữ để sử dụng, hãy đọc tài liệu về nội dung bản địa hoá.

Hãy xem phần Tạo kiểu cho tiện ích Tự động hoàn thành và SearchBox để tuỳ chỉnh giao diện tiện ích.

Thêm tiện ích SearchBox

SearchBox cho phép người dùng thực hiện tìm kiếm địa lý dựa trên văn bản, chẳng hạn như "pizza ở New York" hoặc "cửa hàng giày gần đường Robson". Bạn có thể đính kèm SearchBox vào một trường văn bản và khi văn bản được nhập, dịch vụ sẽ trả về các dự đoán dưới dạng danh sách chọn thả xuống.

SearchBox cung cấp danh sách mở rộng các cụm từ gợi ý, có thể bao gồm các địa điểm (theo định nghĩa của Places API) cùng với các cụm từ tìm kiếm được đề xuất. Ví dụ: nếu người dùng nhập "pizza ở new", danh sách lựa chọn có thể bao gồm cụm từ "pizza ở New York, NY" cũng như tên của nhiều cửa hàng pizza. Khi người dùng chọn một địa điểm trong danh sách, thông tin về địa điểm đó sẽ được trả về đối tượng SearchBox và ứng dụng của bạn có thể truy xuất thông tin này.

Hàm khởi tạo SearchBox 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ụ SearchBox sẽ theo dõi và đính kèm kết quả.
• Một đối số options có thể chứa thuộc tính bounds: bounds là một đối tượng google.maps.LatLngBounds chỉ định khu vực để tìm kiếm địa điểm. Kết quả sẽ thiên về, nhưng không giới hạn ở những địa điểm nằm trong phạm vi này.

Đoạn mã sau đây sử dụng tham số bounds để điều chỉnh kết quả theo những địa điểm trong một khu vực địa lý cụ thể, được chỉ định bằng cách sử dụng toạ độ vĩ độ/kinh độ.

var defaultBounds = new google.maps.LatLngBounds(
  new google.maps.LatLng(-33.8902, 151.1759),
  new google.maps.LatLng(-33.8474, 151.2631));

var input = document.getElementById('searchTextField');

var searchBox = new google.maps.places.SearchBox(input, {
  bounds: defaultBounds
});

Thay đổi khu vực tìm kiếm cho SearchBox

Để thay đổi khu vực tìm kiếm cho SearchBox hiện có, hãy gọi setBounds() trên đối tượng SearchBox và truyền đối tượng LatLngBounds có liên quan.

Xem ví dụ

Lấy thông tin về địa điểm

Khi người dùng chọn một mục trong số các cụm từ dự đoán được đính kèm vào hộp tìm kiếm, dịch vụ sẽ kích hoạt một sự kiện places_changed. Bạn có thể gọi getPlaces() trên đối tượng SearchBox để truy xuất một mảng chứa nhiều dự đoán, mỗi dự đoán là một đối tượng PlaceResult.

Để biết thêm thông tin về đối tượng PlaceResult, hãy tham khảo tài liệu về kết quả chi tiết về địa điểm.

// Listen for the event fired when the user selects a prediction and retrieve
// more details for that place.
searchBox.addListener("places_changed", () => {
  const places = searchBox.getPlaces();

  if (places.length == 0) {
    return;
  }

  // Clear out the old markers.
  markers.forEach((marker) => {
    marker.setMap(null);
  });
  markers = [];

  // For each place, get the icon, name and location.
  const bounds = new google.maps.LatLngBounds();

  places.forEach((place) => {
    if (!place.geometry || !place.geometry.location) {
      console.log("Returned place contains no geometry");
      return;
    }

    const icon = {
      url: place.icon as string,
      size: new google.maps.Size(71, 71),
      origin: new google.maps.Point(0, 0),
      anchor: new google.maps.Point(17, 34),
      scaledSize: new google.maps.Size(25, 25),
    };

    // Create a marker for each place.
    markers.push(
      new google.maps.Marker({
        map,
        icon,
        title: place.name,
        position: place.geometry.location,
      })
    );

    if (place.geometry.viewport) {
      // Only geocodes have viewport.
      bounds.union(place.geometry.viewport);
    } else {
      bounds.extend(place.geometry.location);
    }
  });
  map.fitBounds(bounds);
});
index.ts

// Listen for the event fired when the user selects a prediction and retrieve
// more details for that place.
searchBox.addListener("places_changed", () => {
  const places = searchBox.getPlaces();

  if (places.length == 0) {
    return;
  }

  // Clear out the old markers.
  markers.forEach((marker) => {
    marker.setMap(null);
  });
  markers = [];

  // For each place, get the icon, name and location.
  const bounds = new google.maps.LatLngBounds();

  places.forEach((place) => {
    if (!place.geometry || !place.geometry.location) {
      console.log("Returned place contains no geometry");
      return;
    }

    const icon = {
      url: place.icon,
      size: new google.maps.Size(71, 71),
      origin: new google.maps.Point(0, 0),
      anchor: new google.maps.Point(17, 34),
      scaledSize: new google.maps.Size(25, 25),
    };

    // Create a marker for each place.
    markers.push(
      new google.maps.Marker({
        map,
        icon,
        title: place.name,
        position: place.geometry.location,
      }),
    );
    if (place.geometry.viewport) {
      // Only geocodes have viewport.
      bounds.union(place.geometry.viewport);
    } else {
      bounds.extend(place.geometry.location);
    }
  });
  map.fitBounds(bounds);
});
index.js

Xem ví dụ

Hãy xem phần Tạo kiểu cho tiện ích Tự động hoàn thành và SearchBox để tuỳ chỉnh giao diện tiện ích.

Truy xuất các cụm từ gợi ý của Dịch vụ tự động hoàn thành địa điểm theo phương thức lập trình

Để truy xuất các dự đoán theo phương thức lập trình, hãy sử dụng lớp AutocompleteService. AutocompleteService không thêm bất kỳ chế độ kiểm soát nào trên giao diện người dùng. Thay vào đó, phương thức này trả về một mảng các đối tượng dự đoán, mỗi đối tượng chứa văn bản của dự đoán, thông tin tham chiếu và thông tin chi tiết về cách kết quả khớp với dữ liệu đầu vào của người dùng. Điều này sẽ hữu ích nếu bạn muốn kiểm soát giao diện người dùng nhiều hơn so với Autocomplete và SearchBox được mô tả ở trên.

AutocompleteService hiển thị các phương thức sau:

• getPlacePredictions() trả về các đề xuất về địa điểm. Lưu ý: "Địa điểm" có thể là một cơ sở, vị trí địa lý hoặc địa điểm yêu thích nổi bật, theo định nghĩa của Places API.
• getQueryPredictions() trả về một danh sách mở rộng gồm các thông tin dự đoán, có thể bao gồm các địa điểm (theo định nghĩa của Places API) cùng với các cụm từ tìm kiếm được đề xuất. Ví dụ: nếu người dùng nhập "pizza ở new", danh sách lựa chọn có thể bao gồm cụm từ "pizza ở New York, NY" cũng như tên của nhiều cửa hàng pizza.

Cả hai phương thức trên đều trả về một mảng gồm các đối tượng dự đoán có dạng sau:

• description là dự đoán phù hợp.
• distance_meters là khoảng cách (tính bằng mét) từ địa điểm đến AutocompletionRequest.origin đã chỉ định.
• matched_substrings chứa một tập hợp các chuỗi con trong nội dung mô tả khớp với các phần tử trong dữ liệu đầu vào của người dùng. Điều này hữu ích cho việc làm nổi bật những chuỗi con đó trong ứng dụng của bạn. Trong nhiều trường hợp, cụm từ tìm kiếm sẽ xuất hiện dưới dạng một chuỗi con của trường nội dung mô tả.
  • length là độ dài của chuỗi con.
  • offset là mức chênh lệch ký tự, được đo từ đầu chuỗi nội dung mô tả, tại đó chuỗi con được so khớp xuất hiện.
• place_id là giá trị nhận dạng dạng văn bản xác định một địa điểm duy nhất. Để truy xuất thông tin về địa điểm, hãy truyền giá trị nhận dạng này vào trường placeId của một yêu cầu Chi tiết về địa điểm. Tìm hiểu thêm về cách tham chiếu một địa điểm bằng mã địa điểm.
• terms là một mảng chứa các phần tử của truy vấn. Đối với một địa điểm, mỗi phần tử thường sẽ tạo thành một phần của địa chỉ.
  • offset là mức chênh lệch ký tự, được đo từ đầu chuỗi nội dung mô tả, tại đó chuỗi con được so khớp xuất hiện.
  • value là cụm từ khớp.

Ví dụ bên dưới thực thi một yêu cầu dự đoán truy vấn cho cụm từ "pizza near" (pizza gần đây) và hiển thị kết quả trong một danh sách.

// This example retrieves autocomplete predictions programmatically from the
// autocomplete service, and displays them as an HTML list.
// This example requires the Places library. Include the libraries=places
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places">
function initService(): void {
  const displaySuggestions = function (
    predictions: google.maps.places.QueryAutocompletePrediction[] | null,
    status: google.maps.places.PlacesServiceStatus
  ) {
    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") as HTMLUListElement).appendChild(li);
    });
  };

  const service = new google.maps.places.AutocompleteService();

  service.getQueryPredictions({ input: "pizza near Syd" }, displaySuggestions);
}

declare global {
  interface Window {
    initService: () => void;
  }
}
window.initService = initService;
index.ts

// This example retrieves autocomplete predictions programmatically from the
// autocomplete service, and displays them as an HTML list.
// This example requires the Places library. Include the libraries=places
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places">
function initService() {
  const displaySuggestions = function (predictions, status) {
    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 service = new google.maps.places.AutocompleteService();

  service.getQueryPredictions({ input: "pizza near Syd" }, displaySuggestions);
}

window.initService = initService;
index.js

style.css

<html>
  <head>
    <title>Retrieving Autocomplete Predictions</title>

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
  </head>
  <body>
    <p>Query suggestions for 'pizza near Syd':</p>
    <ul id="results"></ul>
    <!-- Replace Powered By Google image src with self hosted image. https://developers.google.com/maps/documentation/places/web-service/policies#other_attribution_requirements -->
    <img
      class="powered-by-google"
      src="https://storage.googleapis.com/geo-devrel-public-buckets/powered_by_google_on_white.png"
      alt="Powered by Google"
    />

    <!-- 
      The `defer` attribute causes the script to execute after the full HTML
      document has been parsed. For non-blocking uses, avoiding race conditions,
      and consistent behavior across browsers, consider loading using Promises. See
      https://developers.google.com/maps/documentation/javascript/load-maps-js-api
      for more information.
      -->
    <script
      src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initService&libraries=places&v=weekly"
      defer
    ></script>
  </body>
</html>
index.html

Xem ví dụ

Mã thông báo phiên

AutocompleteService.getPlacePredictions()có thể sử dụng mã thông báo phiên (nếu được triển khai) để nhóm các yêu cầu tự động hoàn thành cho mục đích thanh toán. Mã thông báo phiên nhóm các giai đoạn truy vấn và lựa chọn của một cụm từ tìm kiếm tự động hoàn thành của người dùng thành một phiên riêng biệt cho mục đích thanh toán. Phiên bắt đầu khi người dùng bắt đầu nhập một cụm từ tìm kiếm và kết thúc khi họ chọn một địa điểm. Mỗi phiên có thể có nhiều cụm từ tìm kiếm, sau đó là một lựa chọn về địa điểm. Sau khi một phiên kết thúc, mã thông báo sẽ không còn hợp lệ. Ứng dụng của bạn phải tạo một mã thông báo mới cho mỗi phiên. Bạn nên sử dụng mã thông báo phiên cho tất cả các phiên tự động hoàn thành. Nếu bạn bỏ qua tham số sessionToken hoặc nếu bạn sử dụng lại mã thông báo phiên, thì phiên sẽ bị tính phí như thể bạn không cung cấp mã thông báo phiên (mỗi yêu cầu sẽ được tính phí riêng).

Bạn có thể sử dụng cùng một mã thông báo phiên để thực hiện một yêu cầu Chi tiết về địa điểm trên địa điểm nhận được từ một lệnh gọi đến AutocompleteService.getPlacePredictions(). Trong trường hợp này, yêu cầu tự động hoàn thành được kết hợp với yêu cầu Chi tiết về địa điểm và lệnh gọi được tính phí như một yêu cầu Chi tiết về địa điểm thông thường. Không tính phí cho yêu cầu tự động hoàn thành.

Hãy nhớ truyền một mã thông báo phiên duy nhất cho mỗi phiên mới. Việc sử dụng cùng một mã thông báo cho nhiều phiên Tự động hoàn thành sẽ làm mất hiệu lực các phiên Tự động hoàn thành đó và tất cả yêu cầu Tự động hoàn thành trong các phiên không hợp lệ sẽ bị tính phí riêng lẻ bằng SKU Tự động hoàn thành theo yêu cầu. Đọc thêm về mã thông báo phiên.

Ví dụ sau đây cho thấy cách tạo mã thông báo phiên, sau đó truyền mã thông báo đó trong AutocompleteService (hàm displaySuggestions() đã bị bỏ qua để ngắn gọn):

// Create a new session token.
var sessionToken = new google.maps.places.AutocompleteSessionToken();

// Pass the token to the autocomplete service.
var autocompleteService = new google.maps.places.AutocompleteService();
autocompleteService.getPlacePredictions({
  input: 'pizza near Syd',
  sessionToken: sessionToken
},
displaySuggestions);

Hãy nhớ truyền một mã thông báo phiên duy nhất cho mỗi phiên mới. Nếu bạn dùng cùng một mã thông báo cho nhiều phiên, thì mỗi yêu cầu sẽ được tính phí riêng.

Đọc thêm về mã thông báo phiên.

Tạo kiểu cho các tiện ích Tự động hoàn thành và Hộp tìm kiếm

Theo mặc định, các phần tử trên giao diện người dùng do Autocomplete và SearchBox cung cấp được tạo kiểu để đưa vào bản đồ Google. Bạn có thể muốn điều chỉnh kiểu cho phù hợp với trang web của riêng mình. Các lớp CSS sau đây có sẵn. Tất cả các lớp được liệt kê bên dưới đều áp dụng cho cả tiện ích Autocomplete và SearchBox.

Tối ưu hoá Place Autocomplete (Phiên bản cũ)

Phần này mô tả các phương pháp hay nhất giúp bạn khai thác tối đa dịch vụ Place Autocomplete (Legacy).

Dưới đây là một số nguyên tắc chung:

• Cách nhanh nhất để phát triển giao diện người dùng hoạt động là sử dụng tiện ích Tự động hoàn thành địa điểm (Cũ) của Maps JavaScript API, tiện ích Tự động hoàn thành địa điểm (Cũ) của Places SDK cho Android hoặc thành phần kiểm soát giao diện người dùng Tự động hoàn thành địa điểm (Cũ) của Places SDK cho iOS
• Ngay từ đầu, hãy tìm hiểu về các trường dữ liệu cần thiết của tính năng Tự động hoàn thành địa điểm (Phiên bản cũ).
• Các trường thiên vị vị trí và hạn chế vị trí là không bắt buộc nhưng có thể ảnh hưởng đáng kể đến hiệu suất của tính năng tự động hoàn thành.
• Sử dụng tính năng xử lý lỗi để đảm bảo ứng dụng của bạn giảm hiệu suất một cách thích hợp nếu API trả về lỗi.
• Đảm bảo ứng dụng của bạn xử lý khi không có lựa chọn nào và cung cấp cho người dùng cách để tiếp tục.

Các phương pháp hay nhất để tối ưu hoá chi phí

Tối ưu hoá chi phí cơ bản

Để tối ưu hoá chi phí sử dụng dịch vụ Tự động hoàn thành địa điểm (Cũ), hãy sử dụng mặt nạ trường trong các tiện ích Chi tiết về địa điểm (Cũ) và Tự động hoàn thành địa điểm (Cũ) để chỉ trả về các trường dữ liệu địa điểm mà bạn cần.

Tối ưu hoá chi phí nâng cao

Hãy cân nhắc việc triển khai theo chương trình tính năng Tự động hoàn thành địa điểm (Phiên bản cũ) để truy cập vào mức giá Theo yêu cầu và yêu cầu kết quả Geocoding API về địa điểm đã chọn thay vì Chi tiết về địa điểm (Phiên bản cũ). Mức giá Theo yêu cầu kết hợp với Geocoding API sẽ tiết kiệm chi phí hơn so với mức giá Theo phiên (dựa trên phiên) nếu cả hai điều kiện sau đều được đáp ứng:

• Nếu bạn chỉ cần vĩ độ/kinh độ hoặc địa chỉ của địa điểm mà người dùng đã chọn, thì Geocoding API sẽ cung cấp thông tin này cho ít hơn một lệnh gọi Place Details (Legacy).
• Nếu người dùng chọn một cụm từ gợi ý tự động hoàn thành trong trung bình 4 yêu cầu gợi ý tự động hoàn thành địa điểm (phiên bản cũ) hoặc ít hơn, thì mức giá Theo yêu cầu có thể tiết kiệm chi phí hơn so với mức giá Theo phiên.

Ứng dụng của bạn có yêu cầu thông tin nào khác ngoài địa chỉ và vĩ độ/kinh độ của kết quả dự đoán đã chọn không?

Các phương pháp hay nhất về hiệu suất

Các nguyên tắc sau đây mô tả những cách tối ưu hoá hiệu suất của tính năng Tự động hoàn thành địa điểm (Phiên bản cũ):

• Thêm các quy định hạn chế về quốc gia, thiên vị vị trí và (đối với các cách triển khai có lập trình) lựa chọn ưu tiên về ngôn ngữ vào cách triển khai Place Autocomplete (Cũ). Không cần lựa chọn ưu tiên về ngôn ngữ đối với các tiện ích vì chúng chọn lựa chọn ưu tiên về ngôn ngữ từ trình duyệt hoặc thiết bị di động của người dùng.
• Nếu Place Autocomplete (Legacy) đi kèm với bản đồ, bạn có thể điều chỉnh vị trí theo khung hiển thị bản đồ.
• Trong trường hợp người dùng không chọn một trong các kết quả dự đoán của tính năng Tự động hoàn thành địa điểm (phiên bản cũ), thường là do không có kết quả dự đoán nào là địa chỉ mà họ muốn, bạn có thể sử dụng lại thông tin đầu vào ban đầu của người dùng để cố gắng nhận được kết quả phù hợp hơn:
  • Nếu bạn chỉ muốn người dùng nhập thông tin địa chỉ, hãy sử dụng lại thông tin đầu vào ban đầu của người dùng trong một lệnh gọi đến Geocoding API.
  • Nếu bạn muốn người dùng nhập cụm từ tìm kiếm cho một địa điểm cụ thể theo tên hoặc địa chỉ, hãy sử dụng yêu cầu Tìm địa điểm (Phiên bản cũ). Nếu chỉ mong đợi kết quả ở một khu vực cụ thể, hãy sử dụng thiên vị vị trí.
  Các trường hợp khác mà bạn nên quay lại dùng Geocoding API bao gồm:
  • Người dùng nhập địa chỉ của cơ sở phụ, chẳng hạn như địa chỉ của các căn hộ hoặc đơn vị cụ thể trong một toà nhà. Ví dụ: địa chỉ "Stroupežnického 3191/17, Praha" của Cộng hoà Séc sẽ cho ra một cụm từ gợi ý một phần trong tính năng Tự động hoàn thành địa điểm (Phiên bản cũ).
  • Người dùng nhập địa chỉ có tiền tố đoạn đường như "23-30 29th St, Queens" ở Thành phố New York hoặc "47-380 Kamehameha Hwy, Kaneohe" trên đảo Kauai ở Hawaii.

Hạn mức sử dụng

Hạn mức

Để biết thông tin về hạn mức và giá, hãy xem tài liệu về Mức sử dụng và Thanh toán cho Places API.