Thông báo bảo mật: Chúng tôi đã nhận thấy một vấn đề bảo mật có thể ảnh hưởng đến các trang web sử dụng các thư viện cụ thể của bên thứ ba (bao gồm cả polyfill.io). Vấn đề này đôi khi có thể chuyển hướng khách truy cập khỏi trang web mong muốn mà chủ sở hữu trang web không biết hoặc không cho phép. Nhiều mẫu JavaScript của chúng tôi trước đây đã bao gồm phần khai báo tập lệnh polyfill.io. Chúng tôi đã xoá phương thức này khỏi các mẫu của mình. Nếu đã sử dụng các mẫu JavaScript có chứa nội dung khai báo này, bạn nên xoá nội dung khai báo.
Trang này mô tả thư viện phía máy khách có sẵn với API JavaScript của Maps. Nếu bạn muốn hợp tác với
Vị trí của dịch vụ web API trên máy chủ của bạn, 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 Ứng dụng Java, Ứng dụng Python và Ứng dụng Go cho Dịch vụ Google Maps.
Giới thiệu
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
hành vi tìm kiếm nhập trước của trường tìm kiếm của Google Maps.
Dịch vụ tự động điền có thể so khớp theo từ đầy đủ và chuỗi con, phân giải tên địa điểm, địa chỉ và mã plus. 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 API Địa điểm, "địa điểm" có thể là một cơ sở, vị trí địa lý hoặc một đ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 API Maps JavaScript, trước tiên hãy đảm bảo
mà API Địa điểm được bật trong Google Cloud Console, trong cùng một
dự án bạn thiết lập cho API Maps JavaScript.
Nhấp vào nút Select a project (Chọn dự án), rồi chọn chính dự án mà bạn đã thiết lập
cho API Maps JavaScript rồi nhấp vào Mở.
Trong danh sách API trên Trang tổng quan, hãy tìm API Địa điểm.
Nếu thấy API trong danh sách thì bạn đã hoàn tất. Nếu API không có trong danh sách,
bật:
Ở đầu trang, hãy chọn ENABLE API (BẬT API) để hiển thị
Thẻ Thư viện. Ngoài ra, trên trình đơn bên trái, hãy chọn Thư viện.
Tìm kiếm API Địa điểm, sau đó chọn API đó từ
danh sách kết quả.
Chọn BẬT. Khi quá trình này kết thúc,
API Địa điểm xuất hiện trong danh sách API trên
Trang tổng quan.
Đang 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 Maps JavaScript chính. Để sử dụng chức năng có trong thư viện này, trước tiên, bạn phải tải chức năng đó bằng tham số libraries trong URL khởi động của API Maps:
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 qua
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 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 thêm trường nhập văn bản vào trang web của bạn,
và theo dõi trường đó để xem 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 ý địa điểm ở dạng
danh sách lựa chọn 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à có thể được truy xuất
theo ứng dụng của bạn. 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 chọnHình 2: Biểu mẫu địa chỉ đã hoàn chỉnh
SearchBox thêm trường nhập văn bản vào trang web của bạn, tương tự như Autocomplete. Có những điểm khác biệt như sau:
Điểm khác biệt chính nằm ở kết quả xuất hiện trong danh sách chọn. SearchBox nguồn cung cấp
một danh sách mở rộng các dự đoán, có thể bao gồm các địa điểm (như được xác định bởi
API Địa điểm) 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 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 tuỳ chọn hơn Autocomplete để hạn chế nội dung tìm kiếm. Trong trường hợp trước, bạn có thể nghiêng về một LatLngBounds nhất định. Trong trường hợp thứ hai, bạn có thể hạn chế tìm kiếm ở một quốc gia cụ thể và một số loại địa điểm cụ thể, cũng như đặt giới hạn. Để biết thêm thông tin, hãy xem bên dưới.
Hình 3: SearchBox hiển thị cụm từ tìm kiếm và thông tin dự đoán về địa điểm.
Hãy xem thông tin chi tiết bên dưới.
Bạn có thể tạo đố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() tới
truy xuất các địa điểm phù hợp hoặc gọi getQueryPredictions() để
truy xuất đị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ỳ thành phần điều khiển giao diện người dùng nào.
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 nội dung 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
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, cung cấp thông tin dự đoán về địa điểm trong danh sách lựa chọ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 lựa chọn tương ứng với một địa điểm (do API Địa điểm xác định).
Hàm khởi tạo 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à tính năng tự động hoàn thành
sẽ theo dõi và đính kèm kết quả vào.
Mảng dữ liệu fields cần được đưa vào
phản hồi Place Details cho PlaceResult đã chọn của người dùng. Nếu
thuộc tính chưa được thiết lập hoặc nếu ['ALL'] được truyền vào, tất cả các trường có sẵn sẽ được trả về và
được lập hoá đơn cho (không khuyến nghị)
để triển khai phiên bản 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 kiểu rõ ràng hoặc một tập hợp kiểu, như được liệt kê trong các kiểu được hỗ trợ. Nếu không có loại nào được chỉ định, tất cả các loại
đã trả lại.
bounds là đối tượng google.maps.LatLngBounds chỉ định khu vực để tìm kiếm địa điểm. Kết quả thiên lệch, nhưng không giới hạn ở,
địa điểm nằm trong những giới hạn này.
strictBounds là một boolean chỉ định liệu API có phải chỉ trả về những địa điểm nằm hoàn toàn trong khu vực do bounds nhất định 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 dữ liệu đầu vào của người dùng.
Bạn có thể dùng componentRestrictions để giới hạn kết quả
các nhóm cụ thể. Hiện tại, bạn có thể sử dụng componentRestrictions để lọc theo tối đa 5
quốc gia. Quốc gia phải được thông qua dưới dạng một quốc gia tương thích với hai ký tự, theo tiêu chuẩn ISO 3166-1 Alpha-2
. Nhiều quốc gia phải được chuyển 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 kèm theo mã quốc gia, hãy xác minh
mà bạn đang sử dụng mã bao gồm quốc gia, vùng lãnh thổ phụ thuộc và đặc biệt
khu vực địa lý quan tâm mà bạn muốn. Bạn có thể tìm thấy thông tin mã tại
Wikipedia: Danh sách ISO
Mã quốc gia 3166 hoặc Duyệt web trực tuyến theo ISO
Nền tảng.
placeIdOnly có thể được dùng để hướng dẫn
Tiện ích Autocomplete để chỉ truy xuất Mã địa điểm. Đang gọi
getPlace() trên đối tượng Autocomplete, phương thức
PlaceResult được cung cấp sẽ chỉ có place id,
Đã đặt thuộc tính types và name. Bạn có thể sử dụng hàm được trả về
ID địa điểm cùng với cuộc gọi đến Địa điểm, Mã hóa địa lý, Chỉ đường hoặc Ma trận khoảng cách
luôn miễn phí.
Giới hạn khả năng dự đoán 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 thể hiện tất cả các loại địa điểm và có xu hướ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 địa điểm
Các tuỳ chọn tự động hoàn thành để đưa ra 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 tuỳ chọn khi tạo
Hàm khởi tạo Autocomplete chấp nhận 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 địa điểm thuộc loại establishment, ưu tiên những địa điểm nằm trong khu vực địa lý được chỉ định và chỉ giới hạn kết quả dự đoán ở những địa điểm thuộc 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 về đị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ó.
Đặt tuỳ chọn strictBounds để giới hạn kết quả trong các giới hạn hiện tại, cho dù dựa trên khung nhìn bản đồ hay giới hạn hình chữ nhật.
autocomplete.setOptions({strictBounds:true});
Hạn chế dự đoán ở 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 ở một nhóm cụ thể gồm tối đa 5 quốc gia.
Dùng tuỳ chọn types hoặc gọi setTypes() để ràng buộc
các dự đoán 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 không có quy tắc ràng buộc nào được chỉ định, thì hệ thống sẽ trả về tất cả các loại.
Đố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 số các cụm từ gợi ý được đính kèm với tính năng tự động hoàn thành
trường văn bản, thì dịch vụ sẽ kích hoạt sự kiện place_changed. Cách nhận thông tin chi tiết về địa điểm:
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ý.
Gọi Autocomplete.getPlace()
trên đối tượng Autocomplete để truy xuất PlaceResult
mà sau đó bạn có thể sử dụng để biết thêm thông tin về đối tượng đã chọn
địa điểm.
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ả
trường dữ liệu có sẵn cho địa điểm đã chọn, và bạn sẽ được lập hoá đơn tương ứng.
Sử dụng Autocomplete.setFields()
để chỉ định trường dữ liệu địa điểm nào cần trả về. Đọc thêm về chính sách
Đối tượng PlaceResult, bao gồm 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 vị trí mà bạn sẽ sử dụng.
Đối với biểu mẫu địa chỉ, bạn nên lấy địa chỉ theo đị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 vào một địa chỉ
biểu mẫu.
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 điền tạo ra 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 được bản địa hoá tự động. Nếu bạn
chỉ định giá trị trình giữ chỗ của riêng bạn, bạn phải xử lý việc bản địa hoá giá trị đó
giá trị nhất định trong ứng dụng của bạn. Để biết thông tin về cách Google Maps
API JavaScript chọn ngôn ngữ để sử dụng, vui lòng đọc tài liệu về
bản địa hoá.
SearchBox cho phép người dùng thực hiện theo các bước địa lý dựa trên văn bản
tìm kiếm, 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à dưới dạng
văn bản được nhập, dịch vụ sẽ trả về các gợi ý trong
dưới dạng một danh sách chọn lọc 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 (do Places API xác định) 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 mới", 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 các
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 mà dịch vụ SearchBox sẽ theo dõi và đính kèm kết quả của dịch vụ.
Đố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 giới hạn ở, các địa điểm nằm trong
các giới hạn này.
Mã sau đây sử dụng tham số giới hạn để sai lệch kết quả
đối với các địa điểm trong một khu vực địa lý cụ thể, được chỉ định thông qua
vĩ độ/kinh độ.
Để thay đổi khu vực tìm kiếm cho một SearchBox hiện có, hãy gọi
setBounds() trên đối tượng SearchBox và truyền phương thức
đối tượng LatLngBounds có liên quan.
Khi người dùng chọn một mục trong số các gợi ý đi kèm với cụm từ tìm kiếm
thì dịch vụ này 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ố dự đoán, mỗi dự đoán là
Đố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 nội dung 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 kết quả 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 dự đoán
các đối tượng, mỗi đối tượng chứa văn bản dự đoán, thông tin tham chiếu,
và chi tiết về cách kết quả khớp với hoạt động đầu vào của người dùng.
Điều này rất 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
do Autocomplete và SearchBox cung cấp
được mô tả ở trên.
AutocompleteService hiển thị các phương thức sau:
getPlacePredictions() trả về thông tin dự đoán về địa điểm.
Lưu ý: Một "địa điểm" có thể là một cơ sở, vị trí địa lý hoặc
địa điểm yêu thích, như được xác định bởi Places API.
getQueryPredictions() trả về một danh sách mở rộng gồm
gợi ý, có thể bao gồm địa điểm (như được xác định bởi Places API)
cùng với các cụm từ tìm kiếm đề xuất. Ví dụ: nếu người dùng nhập "pizza ở new", danh sách 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à kết quả dự đoán phù hợp.
distance_meters là khoảng cách tính bằng mét của địa điểm từ AutocompletionRequest.origin đã chỉ định.
matched_substrings chứa một tập hợp chuỗi con trong
mô tả khớp với các phần tử trong thông tin nhập của người dùng. Điều này hữu ích cho việc làm nổi bật các chuỗi con đó trong ứng dụng. Trong nhiều trường hợp, truy vấn 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à độ dời ký tự, được đo từ đầu chuỗi mô tả, tại đó chuỗi con được so khớp xuất hiện.
terms là một mảng chứa các phần tử của truy vấn. Để
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à độ dời ký tự, được đo từ đầu chuỗi mô tả, tại đó chuỗi con được so khớp xuất hiện.
value là từ khoá 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 gần' và hiện kết quả dưới dạng một 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 hoạt động sẽ nhóm các giai đoạn truy vấn và lựa chọn của người dùng
tự động hoàn thành vào 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 truy vấn và kết thúc khi họ chọn một địa điểm. Mỗi phiên có thể có nhiều truy vấn, theo sau là một lựa chọn địa điểm.
Sau khi phiên kết thúc, mã thông báo không còn hợp lệ nữa. Ứ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 sử dụng lại mã thông báo phiên, thì phiên sẽ được tính phí như thể không có mã thông báo phiên nào được cung cấp (mỗi yêu cầu được tính phí riêng).
Bạn có thể sử dụng cùng một mã thông báo phiên để tạo một yêu cầu Thông tin chi tiết về địa điểm về địa điểm thu đượ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 Thông tin chi tiết về địa điểm và lệnh gọi sẽ được tính phí như một yêu cầu Thông tin chi tiết về địa điểm thông thường. Bạn không phải trả 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ẽ được tính phí riêng lẻ bằng cách sử dụ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ạ việc tạo mã thông báo phiên, sau đó truyền mã đó vào một mã
AutocompleteService (displaySuggestions()
hàm đã đượ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 duy nhất cho mỗi phiên mới. Sử dụng cùng một
mã thông báo cho nhiều phiên sẽ dẫn đến việc mỗi yêu cầu sẽ bị tính phí
riêng lẻ.
Tạo kiểu các tiện ích Tự động hoàn thành và SearchBox
Theo mặc định, các thành phần trên giao diện người dùng do Autocomplete cung cấp và
SearchBox đượ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. Các lớp CSS sau đây
sẵn có. 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.
Lớp CSS cho tiện ích Tự động hoàn thành và SearchBox
lớp CSS
Mô tả
pac-container
Phần tử hình ảnh chứa danh sách các cụm từ gợi ý do dịch vụ Tự động hoàn thành địa điểm 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
dự đoán.
pac-item
Một mục trong danh sách dự đoán do tiện ích Autocomplete hoặc SearchBox cung cấp.
pac-item:hover
Mặt hàng khi người dùng di chuột qua mặt hàng đó.
pac-item-selected
Mục khi người dùng chọn mục đó thông qua bàn phím. Lưu ý: Các mục đã chọn sẽ là thành viên của lớp này và lớp pac-item.
pac-item-query
Một span bên trong pac-item là phần chính của 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 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", thuộc tính 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 sẽ có màu
đen. Nếu có bất kỳ văn bản bổ sung nào trong pac-item, thì văn bản đó nằm bên ngoài pac-item-query và kế thừa kiểu của văn bản từ pac-item. Theo mặc định, hộp này có màu xám. Văn bản bổ sung
thường là một địa chỉ.
pac-matched
Phần của kết quả dự đoán được trả về khớp với dữ liệu đầu vào của người dùng. Theo mặc định, văn bản đã khớp này sẽ được đánh dấu bằng văn bản in đậm. Xin lưu ý rằng văn bản đã so khớp có thể nằm ở bất kỳ vị trí nào trong pac-item. Phần này 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 Tự động hoàn thành địa điểm
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ụ Tự động hoàn thành địa điểm.
Hiểu rõ về tính năng Tự động hoàn thành địa điểm thiết yếu
trường dữ liệu ngay từ đầu.
Các trường xu hướng vị trí và giới hạn vị trí là không bắt buộc nhưng có thể
có tác độ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 nhẹ
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 một 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 điền địa điểm, hãy sử dụng mặt nạ trường trong tiện ích Chi tiết địa điểm và Tự động điền địa điểm để 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 tính năng Tự động hoàn thành địa điểm theo phương thức lập trình để truy cập vào Giá theo yêu cầu và yêu cầu Kết quả của API Địa chỉ về địa điểm đã chọn thay vì Thông tin chi tiết về địa điểm. Giá theo Yêu cầu kết hợp với API Địa chỉ được mã hoá địa lý sẽ tiết kiệm chi phí hơn so với 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ĩ độ/kinh độ hoặc địa chỉ của địa điểm mà người dùng đã chọn, thì API Địa chỉ được mã hoá địa lý sẽ cung cấp thông tin này với chi phí thấp hơn một lệnh gọi Thông tin chi tiết về địa điểm.
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 cụm từ gợi ý tự động hoàn thành trở xuống, 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.
Để được trợ giúp trong việc chọn cách triển khai tính năng Tự động hoàn thành địa điểm 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 thông tin dự đoán đã chọn không?
Các chi phí được liệt kê ở đây được tính bằng đô la Mỹ. Vui lòng tham khảo trang Thanh toán trên Nền tảng Google Maps để biết thông tin đầy đủ về giá.
Các phương pháp hay nhất về hiệu suất
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 Tự động hoàn thành về địa điểm:
Thêm các quy định hạn chế về quốc gia, tính năng thiên vị vị trí và lựa chọn ưu tiên về ngôn ngữ (đối với việc triển khai theo phương thức lập trình) vào quá trình triển khai tính năng Tự động hoàn thành địa điểm. Không cần lựa chọn ưu tiên ngôn ngữ
với các tiện ích vì chúng chọn tuỳ chọn ngôn ngữ từ trình duyệt hoặc thiết bị di động của người dùng.
Nếu tính năng Tự động hoàn thành địa điểm đi kèm với một bản đồ, thì bạn có thể dịch chuyển vị trí theo khung nhìn của 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 Tự động hoàn thành, thường là vì 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 dữ liệu đầ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 dữ liệu đầu vào ban đầu của người dùng trong lệnh gọi đến API Mã hoá địa lý.
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.
Nếu bạn chỉ mong đợi kết quả ở một khu vực cụ thể, hãy sử dụng tính năng thiên vị vị trí.
Sau đây là một số trường hợp khác mà bạn nên quay lại sử dụng API Địa chỉ được mã hoá địa lý:
Người dùng nhập địa chỉ cơ sở phụ ở những quốc gia chưa hỗ trợ đầy đủ tính năng Tự động hoàn thành địa điểm cho địa chỉ cơ sở phụ, ví dụ: Cộng hoà Séc, Estonia và Lithuania. Ví dụ: địa chỉ bằng tiếng Séc "Stroupežnického 3191/17, Praha" sẽ cho ra một phần nội dung gợi ý trong tính năng Tự động hoàn thành địa điểm.
Người dùng nhập địa chỉ có tiền tố đoạn đường như "23-30 29th St, Queens" inch
New York City hoặc "47-380 Kamehameha Hwy, Kaneohe" trên đảo Kauai ở Hawaii.
