Trang này mô tả thư viện phía máy khách có sẵn API API Maps. 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ề Ứng dụng Java,
Ứng dụng Python và Go Client 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 API JavaScript của Maps. 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 bạn hành vi tìm kiếm trước của trường tìm kiếm Google Maps.
Dịch vụ tự động hoàn thành có thể so khớp trên toàn bộ từ và chuỗi con, phân giải tên địa chỉ, địa chỉ và mã cộng. Do đó, các ứng dụng có thể gửi truy vấn khi người dùng nhập để đưa ra dự đoán nhanh về địa điểm.
Bắt đầu
Trước khi sử dụng thư viện Địa điểm trong API JavaScript của Maps, trước tiên hãy đảm bảo rằng 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 JavaScript của Maps.
Nhấp vào nút Select a project (Chọn một dự án), sau đó chọn cùng một dự án mà bạn đã thiết lập cho API JavaScript của Maps và nhấp vào Mở.
Từ 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 đã đặt xong. Nếu API không được liệt kê, hãy bật API đó:
Ở đầu trang, hãy chọn ENABLE API (Bật API) để hiển thị thẻ Library. Ngoài ra, trên trình đơn bên trái, hãy chọn Library (Thư viện).
Tìm API Địa điểm, rồi chọn API đó từ danh sách kết quả.
Chọn BẬT. Khi quá trình hoàn tất,
API Địa điểm sẽ 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 JavaScript chính của Maps. Để sử dụng chức năng có trong thư viện này, trước tiên bạn phải tải hàm này bằng cách sử dụng tham số libraries trong URL bootstrap 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 thông qua 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 cách lập trình (xem Tài liệu tham khảo API JavaScript của Maps: Lớp ServiceService).
Dưới đây là tóm tắt về các lớp học có sẵn:
Autocomplete sẽ thêm trường nhập văn bản vào trang web của bạn và theo dõi trường đó cho các mục 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ề kết quả dự đoán địa điểm dưới dạng danh sách 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à ứng dụng có thể truy xuất thông tin đó. Xem chi tiết bên dưới.
Hình 1: Tự động hoàn thành trường văn bản và danh sách chọnHình 2: Biểu mẫu địa chỉ đã điền
SearchBox sẽ thêm trường nhập văn bản vào trang web của bạn, tương tự như Autocomplete. Những điểm khác biệt như sau:
Sự 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 một danh sách dự đoán mở rộng, 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 đề xuất. Ví dụ: nếu người dùng nhập 'pizza ở thế hệ mới', danh sách chọn lọc 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 bán bánh pizza.
SearchBox cung cấp ít tuỳ chọn hơn Autocomplete để hạn chế tìm kiếm. Trước đây, bạn có thể xu hướng tìm kiếm theo một LatLngBounds nhất định. Trong phần sau, bạn có thể giới hạn phạm vi tìm kiếm ở một quốc gia cụ thể và các loại địa điểm cụ thể, cũng như việc đặt giới hạn. Để biết thêm thông tin, hãy xem bên dưới.
Hình 3: Hộp tìm kiếm hiển thị cụm từ tìm kiếm và gợi ý địa điểm.
Hãy 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 dự đoán theo phương thức lập trình. Gọi getPlacePredictions() để
truy xuất đị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ụ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 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 dự đoán, cũng như thông tin tham khảo 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. 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 trường nhập văn bản trên trang web, cung cấp thông tin dự đoán về các địa điểm trong danh sách chọn giao diện người dùng và trả về thông tin chi tiết về địa điểm theo 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 (như được xác định bởi API địa điểm).
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ả.
Một đố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 cần được đưa vào phản hồi Place Details cho PlaceResult đã chọn của người dùng. Nếu bạn không đặt
thuộc tính hoặc nếu ['ALL'] được chuyển vào, tất cả các trường có sẵn sẽ được trả về và
lập hóa đơn (bạn không nên thực hiện việc này
cho quá trình triển khai chính thức). Để biết danh sách trường, hãy xem PlaceResult.
Một mảng types chỉ định một loại hoặc một tập hợp loại rõ ràng, như liệt kê trong các loại được hỗ trợ. Nếu không có loại nào được chỉ định, tất cả các loại sẽ được trả về.
bounds là đối tượng google.maps.LatLngBounds chỉ định khu vực cần tìm kiếm địa điểm. Kết quả được 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.
strictBounds là boolean chỉ định việc API chỉ được trả về những vị trí nằm trong khu vực được bounds xác định. 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 do người dùng nhập.
Bạn có thể sử 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. Các quốc gia phải được chuyển dưới dạng mã quốc gia tương thích gồm hai ký tự, 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 bằng mã quốc gia, hãy xác minh rằng bạn đang sử dụng mã bao gồm quốc gia, vùng lãnh thổ phụ thuộc và các khu vực địa lý đặc biệt mà bạn định sử dụng. Bạn có thể tìm thông tin mã tại
Wikipedia: Danh sách mã quốc gia ISO 3166 hoặc Nền tảng Duyệt web trực tuyến ISO.
Bạn có thể sử dụng placeIdOnly để hướng dẫn tiện ích Autocomplete truy xuất chỉ các Mã địa điểm. Khi gọi getPlace() trên đối tượng Autocomplete, PlaceResult được cung cấp sẽ chỉ đặt các thuộc tính place id, types và name. Bạn có thể sử dụng ID địa điểm được trả về với các lệnh gọi đến dịch vụ Địa điểm, Mã hóa địa lý, Chỉ đường hoặc Ma trận khoảng cách.
Dự đoán tự động điền
Theo mặc định, tính năng Tự động hoàn thành địa điểm sẽ hiển thị tất cả các loại địa điểm, thiên về 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 tuỳ chọn
Tự động hoàn thành địa điểm để đưa ra các thông tin dự đoán phù hợp hơn dựa trên
trường hợp sử dụng của bạn.
Đặt tùy chọn khi xây dựng
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 loại địa điểm establishment, ưu tiên những địa điểm thuộc khu vực địa lý được chỉ định và chỉ đề xuất những địa điểm thuộc Hoa Kỳ. Việc đặt tuỳ chọn fields sẽ chỉ định thông tin trả về về địa điểm mà người dùng chọn.
Gọi setOptions() để thay đổi giá trị của tùy chọn cho một tiện ích con hiện có.
TypeScript
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);
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. Đư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 đối tượng Autocomplete hiện có.
Đặt tuỳ chọn strictBounds để giới hạn kết quả trong phạm vi hiện tại, bất kể là chế độ xem bản đồ hay ranh giới hình chữ nhật.
autocomplete.setOptions({ strictBounds: true });
Hạn chế truy vấn dự đoán ở một quốc gia cụ thể
Hãy 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() để hạn chế gợi ý đối với một số loại địa điểm nhất định. Hạn chế 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ó hạn chế nào được chỉ định, tất cả kiểu sẽ được trả về.
Đối với giá trị của tuỳ chọn types hoặc giá trị được chuyển đến setTypes(), bạn có thể chỉ định:
Khi người dùng chọn một địa điểm trong phần dự đoán đính kèm vào trường văn bản tự động hoàn thành, dịch vụ này 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:
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 đối tượng PlaceResult mà sau đó bạn có thể sử dụng để lấy 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ả trường dữ liệu có sẵn cho địa điểm đã chọn và bạn sẽ được lập hóa đơn tương ứng.
Sử dụng Autocomplete.setFields() để chỉ định 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 trường dữ liệu địa điểm mà bạn có thể yêu cầu. Để tránh phải trả tiền 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 các 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() rồi 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
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();
}
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;
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ỗ 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, vui lòng đọc tài liệu về
địa phương hóa.
SearchBox cho phép người dùng tìm kiếm bằng văn bản địa lý, chẳng hạn như "pizza ở New York" hoặc "cửa hàng giày gần phố 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ụm từ gợi ý dưới dạng danh sách chọn thả xuống.
SearchBox cung cấp một danh sách dự đoán mở rộng, 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 đề xuất. Ví dụ: nếu người dùng nhập "pizza in new", danh sách chọn lọc có thể bao gồm cụm từ "pizza in New York, NY" (Tên cửa hàng pizza ở New York, NY) cũng như tên của các cửa hàng bán 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ả.
Một đối số options có thể chứa thuộc tính bounds: bounds là một đối tượng google.maps.LatLngBounds xác định khu vực cần tìm kiếm các địa điểm. Kết quả thiên về các địa điểm nằm trong các giới hạn này.
Mã sau đây sử dụng tham số ranh giới để xu hướng kết quả về các địa điểm trong một khu vực địa lý cụ thể, được chỉ định thông qua tọa độ kinh độ/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 vùng tìm kiếm cho SearchBox
Để thay đổi vùng 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 đối tượng LatLngBounds có liên quan.
Khi người dùng chọn một mục từ các truy vấn dự đoán đí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ố truy vấn dự đoán, mỗi dự đoán 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", () => {
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);
});
// 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);
});
Truy xuất dự đoán Dịch vụ tự động hoàn thành địa điểm theo phương thức lập trình
Để truy xuất truy vấn 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 đó, hệ thống sẽ 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 khảo 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 khả năng cung cấp của Autocomplete và SearchBox như mô tả ở trên.
AutocompleteService cho thấy các phương thức sau:
getPlacePredictions() trả về các dự đoán địa điểm.
Lưu ý: 'Địa điểm' có thể là một cơ sở, vị trí địa lý hoặc địa điểm
nổi bật, như được xác định bởi API địa điểm.
getQueryPredictions() trả về danh sách gợi ý mở rộng, 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 đề xuất. Ví dụ: nếu người dùng nhập 'pizza ở thế hệ mới', danh sách chọn lọc 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 bán pizza.
Cả hai phương thức trên đều trả về một mảng các đối tượng dự đoán có dạng như sau:
description là dự đoán được đối sánh.
distance_meters là khoảng cách tính bằng mét của địa điểm tính từ AutocompletionRequest.origin được chỉ định.
matched_substrings chứa một tập hợp con gồm các chuỗi con trong phần mô tả khớp với các phần tử trong dữ liệu nhập của người dùng. Điều này rất hữu ích khi 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à độ lệch ký tự, được đo từ đầu chuỗi mô tả, tại đó chuỗi con xuất hiện.
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ẽ chiếm một phần địa chỉ.
offset là độ lệch ký tự, được đo từ đầu chuỗi mô tả, tại đó chuỗi con xuất hiện.
value là cụm từ phù hợp.
Ví dụ bên dưới sẽ thực thi yêu cầu dự đoán truy vấn 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">
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;
// 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;
<html>
<head>
<title>Retrieving Autocomplete Predictions</title>
<script src="https://polyfill.io/v3/polyfill.min.js?features=default"></script>
<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 callback 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() sử dụng mã thông báo phiên để 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 sẽ 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 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 truy vấn và kết thúc khi 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ệ. Ứng dụng 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 tham số sessionToken bị bỏ qua 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ể không có mã thông báo phiên nào được cung cấp (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 để tạo một yêu cầu
Thông tin chi tiết về địa điểm
cho địa điểm phát sinh 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à cuộc gọi sẽ được tính phí như một yêu cầu Chi tiết về địa điểm thông thường. Bạn sẽ không phải trả phí cho yêu cầu tự động hoàn thành.
Hãy nhớ truyền 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ả cá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 Tự động hoàn thành
theo SKU yêu cầu. Đọc thêm về mã thông báo phiên.
Ví dụ sau đây cho thấy việc tạo một mã thông báo phiên, sau đó truyền vào AutocompleteService (hàm displaySuggestions() đã được bỏ qua cho 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ã 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 trong nhiều phiên sẽ khiến từng yêu cầu bị tính phí riêng lẻ.
Định kiểu cho 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 và SearchBox cung cấp được tạo kiểu để đưa vào bản đồ trê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ác lớp CSS sau đây. Tất cả các lớp trong danh sách dưới đây đều áp dụng cho cả tiện ích Autocomplete và SearchBox.
Các lớp CSS dành 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 truy vấn dự đoán do dịch vụ Tự động điền địa điểm trả về. Danh sách này xuất hiện dưới dạng một danh sách thả xuống bên dưới tiện ích Autocomplete hoặc SearchBox.
pac-icon
Biểu tượng này nằm ở bên trái từng 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 chuột qua mục đó.
pac-item-selected
Mục khi người dùng chọn mục đó 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à của lớp pac-item.
pac-item-query
Span bên trong pac-item là thành phần chính của thành phần dự đoán. Đối với các vị trí địa lý, tên này chứa tên địa điểm, như
'Sydney' hoặc tên đường phố và số, như '10 King Street'. Đối với kết quả tìm kiếm dạng văn bản, chẳng hạn như "pizza ở New York", kết quả này sẽ bao gồm toàn bộ nội dung 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, văn bản đó sẽ ở bên ngoài pac-item-query và kế thừa kiểu từ pac-item. Theo mặc định, màu này là màu xám. Văn bản bổ sung thường là một địa chỉ.
pac-matched
Phần dự đoán được trả về khớp với thông tin do người dùng nhập. Theo mặc định, văn bản phù hợp này được làm nổi bật bằng văn bản in đậm. Lưu ý rằng văn bản phù hợ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 mà có thể một phần nằm trong pac-item-query cũng như trong văn bản còn lại của 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.
Nâng cao hiểu biết về các trường dữ liệu Tự động điền địa điểm cần thiết ngay từ đầu.
Xu hướng vị trí và các trường hạn chế vị trí là tùy chọn 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ẹ nhàng nếu API trả về lỗi.
Hãy đảm bảo ứng dụng của bạn xử lý các trường hợp không được lựa chọn và cho người dùng cách để tiếp tục.
Các phương pháp hay nhất để tối ưu hóa chi phí
Tối ưu hóa 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, hãy sử dụng mặt nạ trường trong tiện ích Chi tiết địa điểm và Tự động hoàn thành địa điểm để chỉ trả về trường dữ liệu địa điểm mà bạn cần.
Tối ưu hoá chi phí nâng cao
Cân nhắc triển khai có lập trình của tính năng Tự động hoàn thành địa điểm để truy cập vào Giá cho mỗi yêu cầu và yêu cầu kết quả API mã hóa địa lý về địa điểm đã chọn thay vì Chi tiết địa điểm. Giá cho mỗi yêu cầu kết hợp với API mã hóa địa lý có hiệu quả về chi phí hơn so với đặt giá cho mỗi phiên (dựa trên phiên) nếu cả hai điều kiện sau đượ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, API mã hóa địa lý sẽ cung cấp thông tin này cho một lệnh gọi Chi tiết Địa điểm.
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 vòng trung bình bốn yêu cầu dự đoán Tự động hoàn thành hoặc ít hơn, thì tùy chọn đặt giá theo Yêu cầu có thể tiết kiệm chi phí hơn so với đặt giá Theo phiên.
Để được trợ giúp chọn cách triển khai tính năng Tự động điền đị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 cụm từ gợi ý bạn đã chọn không?
Các nguyên tắc sau đây mô tả cách tối ưu hóa hiệu suất Tự động hoàn thành địa điểm:
Thêm các hạn chế theo quốc gia, xu hướng vị trí và tuỳ chọn ngôn ngữ (đối với các hoạt động triển khai 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. Bạn không cần tuỳ chọn ngôn ngữ cho các tiện ích vì các tiện ích này sẽ chọn các lựa chọn ưu tiên về ngôn ngữ trên trình duyệt hoặc thiết bị di động của người dùng.
Nếu Tự động điền địa điểm đi kèm với một bản đồ, bạn có thể thiên vị trí bằng chế độ xem bản đồ.
Trong các trường hợp khi 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 thông tin đầu vào ban đầu của người dù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 API mã hóa địa lý.
Nếu bạn muốn người dùng nhập truy vấn cho một địa điểm cụ thể theo tên hoặc địa chỉ, hãy dùng Yêu cầu tìm địa điểm.
Nếu kết quả chỉ mong đợi ở một khu vực cụ thể, hãy sử dụng xu hướng vị trí.
Các trường hợp khác khi tốt nhất nên quay lại dùng API mã hóa địa lý:
Người dùng nhập địa chỉ phụ ở các quốc gia mà tính năng hỗ trợ Tự động điền địa điểm chưa đầy đủ, ví dụ: Séc, Estonia và Lithuania. Ví dụ: địa chỉ tiếng Séc "Stroupežnického 3191/17, Praha" tạo 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.
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 ở Hawai'i.
