Place Autocomplete (Cũ)
Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang
Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.
Nhà phát triển ở Khu vực kinh tế Châu Âu (EEA)
Lưu ý: Thư viện phía máy chủ
Trang này mô tả thư viện phía máy khách có trong Maps JavaScript API. Nếu bạn muốn làm việc với dịch vụ web API Địa điểm trên máy chủ của mình, hãy xem Ứng dụng Node.js cho Dịch vụ Google Maps. Trang tại đường liên kết đó cũng giới thiệu về Java Client, Python Client và Go Client cho Dịch vụ Google Maps.
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 ứng dụng của mình hành vi tìm kiếm trước khi nhập 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 các từ và chuỗi con đầy đủ, phân giải tên địa điểm, địa chỉ và Plus Codes. 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 địa điểm nhanh chóng. Theo định nghĩa của Places API, "địa điểm" có thể là một cơ sở, một 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 địa điểm 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.
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ở.
Trong danh sách API trên Trang tổng quan, hãy tìm Places API.
Nếu thấy API trong danh sách, thì bạn đã hoàn tất. Tuy nhiên, dự án này đang ở trạng thái Cũ.
Để biết thêm thông tin về giai đoạn Ngừng hoạt động và cách di chuyển từ sản phẩm/tính năng Ngừng hoạt động sang các dịch vụ mới hơn, hãy xem bài viết Sản phẩm và tính năng Ngừng hoạt động.
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, vì các tiện ích này chưa được cung cấp dưới dạng 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 cho Maps chính. Để 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 bằng tham số libraries trong URL khởi động của API Maps:
API này cung cấp hai 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ể sử 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 API JavaScript của Maps: Lớp AutocompleteService).
Dưới đây là thông tin tóm tắt về các lớp có sẵn:
Autocomplete thêm một trường nhập dữ liệu 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 cụm từ gợi ý 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 đó. Xem thông tin chi tiết bên dưới.
Hình 1: Trường văn bản tự động hoàn thành và danh sách lựa chọnHình 2: Biểu mẫu địa chỉ đã hoàn thành
SearchBox thêm một trường nhập dữ liệu vào trang web của bạn, theo cách 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 lựa chọn. SearchBox cung cấp danh sách cụm từ gợi ý mở rộng, có thể bao gồm các địa điểm (theo định nghĩa của Places API) và các cụm từ tìm kiếm đề xuất. Ví dụ: nếu người dùng
nhập "pizza ở New", thì 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
khác nhau.
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ề tìm kiếm một LatLngBounds nhất định. Trong trường hợp sau, bạn có thể giới hạn kết quả 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.
Hình 3: SearchBox trình bày cụm từ tìm kiếm và thông tin dự đoán về địa điểm.
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ụm từ tìm kiếm đề xuất.
Lưu ý: AutocompleteService không thêm bất kỳ thành phần điều khiển nào trên giao diện người dùng.
Thay vào đó, các phương thức trên trả về một mảng đối tượng dự đoán. Mỗi đối tượng dự đoán chứa văn bản của thông tin 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 thông tin đầ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 dữ liệu 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 lựa chọn trên giao diện người dùng và trả về Place Details để 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 (theo định nghĩa của Places API).
Hàm khởi tạo Autocomplete nhận hai đố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ả vào.
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 này hoặc nếu bạn truyền ['ALL'] vào, thì tất cả các trường có sẵn sẽ được trả về và bị tính phí (bạn không nên làm như vậy khi triển khai chính thức). Để 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, 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ẽ ưu tiên, nhưng không chỉ giới hạn ở,
những địa điểm nằm trong các ranh giới này.
strictBounds là một boolean
chỉ định xem API có phải chỉ trả về những địa điểm nằm hoàn toàn trong khu vực được xác định
bởi bounds đã cho 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 người dùng nhập.
Bạn có thể sử dụng componentRestrictions để giới hạn kết quả cho các nhóm cụ thể. Bạn có thể sử dụng componentRestrictions để lọc theo tối đa 5 quốc gia. Quốc gia phải được truyền dưới dạng mã quốc gia gồm hai 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.
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ề cho các lệnh gọi đến dịch vụ Địa điểm, Mã hoá địa lý, Chỉ đường hoặc Ma trận khoảng cách.
Giới hạn cụm từ gợi ý của tính năng tự động hoàn thành
Theo mặc định, Place Autocomplete sẽ hiển thị tất cả các loại địa điểm, ưu tiên các cụm từ gợi ý 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 cho tính năng Tự động hoàn thành địa điểm để đưa ra các cụm từ gợi ý 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 khi tạo
Hàm khởi tạo Autocomplete chấp nhận 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 tuỳ 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ụm từ gợi ý cho các địa điểm ở Hoa Kỳ. Việc đặt tuỳ 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 tuỳ chọn cho một tiện ích hiện có.
TypeScript
constcenter={lat:50.064192,lng:-130.605469};// Create a bounding box with sides ~10km away from the center pointconstdefaultBounds={north:center.lat+0.1,south:center.lat-0.1,east:center.lng+0.1,west:center.lng-0.1,};constinput=document.getElementById("pac-input")asHTMLInputElement;constoptions={bounds:defaultBounds,componentRestrictions:{country:"us"},fields:["address_components","geometry","icon","name"],strictBounds:false,};constautocomplete=newgoogle.maps.places.Autocomplete(input,options);
constcenter={lat:50.064192,lng:-130.605469};// Create a bounding box with sides ~10km away from the center pointconstdefaultBounds={north:center.lat+0.1,south:center.lat-0.1,east:center.lng+0.1,west:center.lng-0.1,};constinput=document.getElementById("pac-input");constoptions={bounds:defaultBounds,componentRestrictions:{country:"us"},fields:["address_components","geometry","icon","name"],strictBounds:false,};constautocomplete=newgoogle.maps.places.Autocomplete(input,options);
Chỉ định các trường dữ liệu để tránh bị tính phí cho SKU dữ liệu địa điểm mà bạn không cần. Thêm 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 đối tượng Autocomplete hiện có.
Giới hạn kết quả tìm kiếm trong ranh giới hiện tại
Đặt tuỳ chọn strictBounds để giới hạn kết quả trong ranh giới hiện tại, cho dù dựa trên khung nhìn bản đồ hay ranh giới hình chữ nhật.
autocomplete.setOptions({strictBounds:true});
Hạn chế cụm từ gợi ý cho một quốc gia cụ thể
Sử dụng tuỳ chọn componentRestrictions hoặc gọi setComponentRestrictions() để giới hạn tính năng tìm kiếm tự động hoàn thành trong một nhóm cụ thể gồm tối đa 5 quốc gia.
Sử dụng tuỳ chọn types hoặc gọi setTypes() để giới hạn cụm từ gợi ý cho một số loại địa điểm nhất định. Quy tắc 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 Loại địa điểm.
Nếu bạn không chỉ định quy tắc ràng buộc, thì tất cả các loại sẽ được trả về.
Đối với giá trị của tuỳ chọn types hoặc giá trị được truyền đến setTypes(), bạn có thể chỉ định:
Khi người dùng chọn một địa điểm trong các cụm từ gợi ý đượ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 lấy thông tin chi tiết về địa điểm:
Tạo 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ý.
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 thanh toán tương ứng.
Sử dụng Autocomplete.setFields() để chỉ định các trường dữ liệu địa điểm cần trả về. Đọc thêm về đối tượng PlaceResult, bao gồm cả danh sách các trường dữ liệu địa điểm mà bạn có thể yêu cầu. Để tránh phải trả phí cho dữ liệu mà bạn không cần, hãy nhớ sử dụng Autocomplete.setFields() để chỉ định
dữ liệu địa điểm mà bạn sẽ sử dụng.
Đố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 vào các trường trong biểu mẫu địa chỉ.
TypeScript
functionfillInAddress(){// Get the place details from the autocomplete object.constplace=autocomplete.getPlace();letaddress1="";letpostcode="";// 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/3l5i5Mrfor(constcomponentofplace.address_componentsasgoogle.maps.GeocoderAddressComponent[]){// @ts-ignore remove once typings fixedconstcomponentType=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")asHTMLInputElement).value=component.long_name;break;case"administrative_area_level_1":{(document.querySelector("#state")asHTMLInputElement).value=component.short_name;break;}case"country":(document.querySelector("#country")asHTMLInputElement).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();}
functionfillInAddress(){// Get the place details from the autocomplete object.constplace=autocomplete.getPlace();letaddress1="";letpostcode="";// 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/3l5i5Mrfor(constcomponentofplace.address_components){// @ts-ignore remove once typings fixedconstcomponentType=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;
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 phần giữ chỗ 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 phầ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ề
bản địa hoá.
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ề thông tin dự đoán dưới dạng danh sách chọn thả xuống.
SearchBox cung cấp danh sách cụm từ gợi ý mở rộng, có thể bao gồm các địa điểm (theo định nghĩa của Places API) và các cụm từ tìm kiếm đề xuất. Ví dụ: nếu người dùng nhập "pizza ở New", thì 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 đó.
Hàm khởi tạo SearchBox nhận hai đố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ụ SearchBox sẽ theo dõi và đính kèm kết quả.
Đố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ả
thiên về nhưng không chỉ giới hạn ở những địa điểm nằm trong
các ranh giới này.
Mã sau đây sử dụng tham số ranh giới để ưu tiên kết quả cho các địa điểm trong một khu vực địa lý cụ thể, được chỉ định bằng toạ độ vĩ độ/kinh độ.
Khi người dùng chọn một mục trong số các cụm từ gợi ý đượ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 một số cụm từ gợi ý, mỗi cụm từ gợi ý là một đối tượng PlaceResult.
// Listen for the event fired when the user selects a prediction and retrieve// more details for that place.searchBox.addListener("places_changed",()=>{constplaces=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.constbounds=newgoogle.maps.LatLngBounds();places.forEach((place)=>{if(!place.geometry||!place.geometry.location){console.log("Returned place contains no geometry");return;}consticon={url:place.iconasstring,size:newgoogle.maps.Size(71,71),origin:newgoogle.maps.Point(0,0),anchor:newgoogle.maps.Point(17,34),scaledSize:newgoogle.maps.Size(25,25),};// Create a marker for each place.markers.push(newgoogle.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);});
// Listen for the event fired when the user selects a prediction and retrieve// more details for that place.searchBox.addListener("places_changed",()=>{constplaces=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.constbounds=newgoogle.maps.LatLngBounds();places.forEach((place)=>{if(!place.geometry||!place.geometry.location){console.log("Returned place contains no geometry");return;}consticon={url:place.icon,size:newgoogle.maps.Size(71,71),origin:newgoogle.maps.Point(0,0),anchor:newgoogle.maps.Point(17,34),scaledSize:newgoogle.maps.Size(25,25),};// Create a marker for each place.markers.push(newgoogle.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);});
Truy xuất các cụm từ gợi ý của Dịch vụ Place Autocomplete theo phương thức lập trình
Để truy xuất thông tin 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ỳ thành phần điều khiển 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 thông tin 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 thông tin do người dùng nhập.
Điều này rất hữu ích nếu bạn muốn có nhiều quyền kiểm soát hơn đối với giao diện người dùng 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ụm từ gợi ý 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ề danh sách mở rộng gồm các cụm từ gợi ý, có thể bao gồm các địa điểm (theo định nghĩa của API Địa điểm) và các cụm từ tìm kiếm được đề xuất. Ví dụ: nếu người dùng nhập "pizza ở New", thì 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
đối tượng
dự đoán có dạng như sau:
description là cụm từ gợi ý phù hợp.
distance_meters là khoảng cách tính bằng mét của địa điểm từ
AutocompletionRequest.origin được chỉ định.
matched_substrings chứa một tập hợp các chuỗi con trong phần 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 rất hữu ích cho việc làm nổi bật các 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 mô tả.
length là độ dài của chuỗi con.
offset là độ lệch ký tự, được đo từ đầu chuỗi mô tả, nơi chuỗi con khớp xuất hiện.
place_id là giá trị nhận dạng dạng văn bản giúp xác định duy nhất một địa điểm. Để 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 yêu cầu Chi tiết đị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à độ lệch ký tự, được đo từ đầu chuỗi mô tả, nơi chuỗi con khớp xuất hiện.
value là cụm từ trùng khớp.
Ví dụ bên dưới thực thi một yêu cầu dự đoán cụm từ tìm kiếm cho cụm từ "pizza gần" và hiển thị kết quả trong danh sách.
TypeScript
// 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">functioninitService():void{constdisplaySuggestions=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)=>{constli=document.createElement("li");li.appendChild(document.createTextNode(prediction.description));(document.getElementById("results")asHTMLUListElement).appendChild(li);});};constservice=newgoogle.maps.places.AutocompleteService();service.getQueryPredictions({input:"pizza near Syd"},displaySuggestions);}declareglobal{interfaceWindow{initService:()=>void;}}window.initService=initService;
// 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">functioninitService(){constdisplaySuggestions=function(predictions,status){if(status!=google.maps.places.PlacesServiceStatus.OK||!predictions){alert(status);return;}predictions.forEach((prediction)=>{constli=document.createElement("li");li.appendChild(document.createTextNode(prediction.description));document.getElementById("results").appendChild(li);});};constservice=newgoogle.maps.places.AutocompleteService();service.getQueryPredictions({input:"pizza near Syd"},displaySuggestions);}window.initService=initService;
<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>
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 lượ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 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 địa điểm.
Sau khi 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ã phiên, thì phiên đó sẽ được tính phí như thể không có mã phiên nào được cung cấp (mỗi yêu cầu được tính phí riêng).
Bạn nên sử dụng cùng một mã phiên để đưa ra một yêu cầu Place Details duy nhất về địa điểm có được 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 địa điểm và lệnh gọi được tính phí như một yêu cầu Chi tiết địa điểm thông thường. Bạn không mất phí cho yêu cầu tự động hoàn thành. Nếu không sử dụng mã phiên cho yêu cầu, bạn sẽ bị tính phí cho cả yêu cầu tự động hoàn thành và yêu cầu Place Details.
Hãy nhớ truyền một mã thông báo phiên riêng biệt cho mỗi phiên mới. Nếu bạn sử dụng cùng một mã thông báo cho nhiều phiên Tự động hoàn thành, thì các phiên Tự động hoàn thành đó sẽ không hợp lệ 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ẽ được tính phí riêng 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 minh hoạ cách tạo mã thông báo phiên, sau đó truyền mã thông báo đó vào một
AutocompleteService (hàm displaySuggestions()
đã được bỏ qua để cho ngắn gọn):
// Create a new session token.varsessionToken=newgoogle.maps.places.AutocompleteSessionToken();// Pass the token to the autocomplete service.varautocompleteService=newgoogle.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 riêng biệt cho mỗi phiên mới. Nếu bạn sử 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.
Tạo kiểu cho tiện ích Tự động hoàn thành và SearchBox
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 nên điều chỉnh kiểu cho phù hợp với trang web của mình. Bạn có thể sử dụng các lớp CSS sau. Tất cả các lớp được liệt kê dưới đây đều áp dụng cho cả tiện ích Autocomplete và SearchBox.
Các lớp CSS cho tiện ích Tự động hoàn thành và Hộp tìm kiếm
Lớp CSS
Mô tả
pac-container
Phần tử hình ảnh chứa danh sách cụm từ gợi ý do dịch vụ Place Autocomplete trả về. Danh sách này xuất hiện dưới dạng danh sách thả xuống bên dưới tiện ích Autocomplete hoặc SearchBox.
pac-icon
Biểu tượng hiển thị ở bên trái của mỗi mục trong danh sách cụm từ gợi ý.
pac-item
Một mục trong danh sách cụm từ gợi ý do tiện ích Autocomplete hoặc SearchBox cung cấp.
pac-item:hover
Mục khi người dùng di con trỏ chuột lên mục đó.
pac-item-selected
Mục khi người dùng chọn mục đó bằng bàn phím. Lưu ý: Các mục đã chọn sẽ là thành viên của lớp học này và lớp học pac-item.
pac-item-query
Một span bên trong pac-item là phần chính của thông tin dự đoán. Đối với vị trí địa lý, trường này chứa tên địa điểm, chẳng hạn như "Sydney" hoặc tên đường và số nhà, chẳng hạn như "10 King Street". Đối với các cụm từ tìm kiếm dựa trên văn bản như "pizza ở New York", trường này chứa toàn bộ văn bản của cụm từ tìm kiếm. Theo mặc định, pac-item-query có màu đen. Nếu có thêm văn bản trong pac-item, thì văn bản đó sẽ nằm ngoài pac-item-query và kế thừa kiểu từ pac-item. Màu mặc định là màu xám. Văn bản bổ sung thường là địa chỉ.
pac-matched
Phần của cụm từ gợi ý được trả về khớp với nội dung người dùng nhập. Theo mặc định, văn bản trùng khớp này được in đậm. Xin lưu ý rằng văn bản trùng khớp có thể nằm ở bất kỳ vị trí nào trong pac-item. Nó không nhất thiết phải là một phần của pac-item-query và có thể nằm một phần trong pac-item-query cũng như một phần trong văn bản còn lại trong pac-item.
Tối ưu hoá tính năng Place Autocomplete (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 (Cũ).
Tìm hiểu ngay từ đầu về các trường dữ liệu thiết yếu của tính năng Place Autocomplete (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 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 xuống cấp một cách linh hoạt nếu API trả về lỗi.
Đảm bảo ứng dụng của bạn xử lý được trường hợp 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ụ Place Autocomplete (Cũ), hãy sử dụng mặt nạ trường trong các tiện ích Place Details (Cũ) và Place Autocomplete (Cũ) để chỉ trả về trường dữ liệu Place Autocomplete (Cũ) mà bạn cần.
Tối ưu hoá chi phí nâng cao
Cân nhắc triển khai Place Autocomplete (Cũ) theo phương thức lập trình để sử dụng
SKU: Tự động hoàn thành – Giá theo yêu cầu
và yêu cầu kết quả của Geocoding API về địa điểm đã chọn thay vì Place Details (Cũ). Mô hình định 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ô hình định giá theo phiên (dựa trên phiên) nếu đáp ứng cả hai điều kiện sau:
Nếu bạn chỉ cần vĩ độ 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 với chi phí thấp hơn so với lệnh gọi Place Details (Cũ).
Nếu người dùng chọn một cụm từ gợi ý của tính năng tự động hoàn thành trong trung bình 4 yêu cầu Place Autocomplete (Cũ) trở xuống, thì mô hình định giá theo yêu cầu có thể tiết kiệm chi phí hơn so với mô hình định giá theo phiên.
Để được trợ giúp chọn cách triển khai tính năng Place Autocomplete (Cũ) phù hợp với nhu cầu của bạn, hãy chọn thẻ tương ứng với câu trả lời của bạn cho câu hỏi sau.
Ứ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 nguyên tắc sau đây mô tả cách tối ưu hoá hiệu suất của tính năng Place Autocomplete (Phiên bản cũ):
Thêm các quy định hạn chế theo quốc gia,
thiên vị vị trí
và (đối với việc triển khai có lập trình) ngôn ngữ ưu tiên vào quá trình triển khai
Place Autocomplete (Cũ). Bạn không cần đặt ngôn ngữ ưu tiên cho các tiện ích vì các tiện ích này sẽ chọn ngôn ngữ ưu tiên từ trình duyệt hoặc thiết bị di động của người dùng.
Nếu Place Autocomplete (Cũ) đi kèm với bản đồ, thì bạn có thể thiên vị vị trí theo khung nhìn bản đồ.
Trong trường hợp người dùng không chọn một trong các cụm từ gợi ý của tính năng Place Autocomplete (Cũ), thường là do không có cụm từ gợi ý nào là địa chỉ kết quả mong 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 muốn người dùng chỉ 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 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 Chi tiết địa điểm (Cũ). Nếu bạn chỉ muốn nhận kết quả ở một khu vực cụ thể, hãy sử dụng tính năng thiên vị vị trí.
Các trường hợp khác mà bạn nên quay lại 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 căn hộ cụ thể
trong một toà nhà. Ví dụ: địa chỉ "Stroupežnického 3191/17, Praha" ở Séc
sẽ trả về một cụm từ gợi ý không đầy đủ trong tính năng Place Autocomplete (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.
Thiên vị vị trí
Tạo độ lệch cho kết quả theo một khu vực cụ thể bằng cách truyền tham số location và tham số radius. Thao tác này hướng dẫn Place Autocomplete (Cũ) ưu tiên hiển thị kết quả trong khu vực đã xác định. Kết quả bên ngoài khu vực đã xác định vẫn có thể xuất hiện. Bạn có thể sử dụng tham số includedRegionCodes để lọc kết quả nhằm chỉ hiển thị những địa điểm trong một quốc gia cụ thể.
Hạn chế về vị trí
Giới hạn kết quả trong một khu vực cụ thể bằng cách truyền tham số locationRestriction.
Bạn cũng có thể giới hạn kết quả ở khu vực được xác định bằng location và tham số radius bằng cách thêm tham số strictbounds. Thao tác này hướng dẫn tính năng Place Autocomplete (Cũ) chỉ trả về kết quả trong khu vực đó.
